Add `ByteString` conversions for JVM `ByteBuffer`

[joffrey-bion]

In the same vibe as #266 and #268, it would be nice to have built-in conversions in kotlinx-io-bytestring for the JVM ByteBuffer type for a full multi-platform experience.

Examples:

/**
 * Exposes the contents of this [ByteString] as a read-only [ByteBuffer] without copying data.
 */
fun ByteString.asReadOnlyByteBuffer(): ByteBuffer = ByteBuffer.wrap(getBackingArrayReference()).asReadOnlyBuffer()

/**
 * Reads all remaining bytes in this [ByteBuffer] into a new [ByteString].
 */
fun ByteBuffer.readByteString(): ByteString = ByteString.wrap(readByteArray())

/**
 * Reads all remaining bytes in this [ByteBuffer] into a new [ByteArray].
 */
// private because that's not really the role of kotlinx-io-bytestring, more of the stdlib
private fun ByteBuffer.readByteArray(): ByteArray {
    val array = ByteArray(remaining())
    get(array)
    return array
}

Arguably the last one could be a stdlib function instead.

[joffrey-bion]

Note: this might slightly overlap with #239, but I still believe it's a different use case, and much easier to add. This is less about using ByteBuffer internally, nor about being able to wrap those directly as backing storage, but more about being able to interop with it conveniently.

[fzhinkin]

@joffrey-bion We already have set of functions wrapping Sinks, Sources, and Buffers into Channels, as well as functions allowing to read/write Buffer from/to ByteBuffer. And there doesn't seem to be a lot of adoption.

Are there any scenarios where proposed functions could be used indeed? Would existing NIO-centric extensions work there?

[joffrey-bion]

Are there any scenarios where proposed functions could be used indeed?

Yes, this is also something I use in Krossbow to wrap the Java web socket APIs.

Would existing NIO-centric extensions work there?

Which extensions are you referring to? In my case the goal is to bridge ByteBuffers (that I get from Java APIs) to ByteStrings (that I expose in my Kotlin API) in the most efficient way.
It could be ok to go through other intermediate representations if this didn't incur more copies than necessary.

[fzhinkin]

Which extensions are you referring to?

• https://kotlin.github.io/kotlinx-io/kotlinx-io-core/kotlinx.io/as-byte-channel.html
• https://kotlin.github.io/kotlinx-io/kotlinx-io-core/kotlinx.io/transfer-from.html
• https://kotlin.github.io/kotlinx-io/kotlinx-io-core/kotlinx.io/read-at-most-to.html
• https://kotlin.github.io/kotlinx-io/kotlinx-io-core/kotlinx.io/write.html

It could be ok to go through other intermediate representations if this didn't incur more copies than necessary.

But yeah, the use of any of those from above implies additional copies. :(

[joffrey-bion]

Thanks! Ok that was my understanding, so yeah I would still need these more direct helpers then.