Add `NSData.toByteString()` and `ByteString.toNSData()` for Apple targets

[joffrey-bion]

It seems that NSData is the Foundation type to represent immutable byte arrays, which means it corresponds to ByteString in purpose. It would be great to have these conversions in the kotlinx-io-bytestring lib by default.

Example implementation:

/**
 * Creates a new [NSData] containing the data copied from this [ByteString].
 */
fun ByteString.toNSData(): NSData = getBackingArrayReference().toNSData()

/**
 * Creates a new [NSData] containing the data copied from this [ByteArray].
 */
@OptIn(ExperimentalForeignApi::class, UnsafeNumber::class, BetaInteropApi::class)
private fun ByteArray.toNSData(): NSData = memScoped {
    NSData.create(bytes = allocArrayOf(this@toNSData), length = this@toNSData.size.convert())
}

/**
 * Creates a new [ByteString] containing the data copied from this [NSData].
 */
fun NSData.toByteString(): ByteString = ByteString.wrap(toByteArray())

/**
 * Creates a new [ByteArray] containing the data copied from this [NSData].
 */
@OptIn(ExperimentalForeignApi::class, UnsafeNumber::class)
private fun NSData.toByteArray(): ByteArray {
    // length=0 breaks memcpy for some reason (ArrayIndexOutOfBoundsException)
    // and it doesn't hurt to skip memcpy anyway if the array is empty
    if (length.toInt() == 0) return ByteArray(0)

    val nsData = this
    return ByteArray(nsData.length.toInt()).apply {
        usePinned { pinned ->
            memcpy(pinned.addressOf(0), nsData.bytes, nsData.length)
        }
    }
}

Arguably, the ByteArray conversions could be part of the stdlib instead, and kotlinx-io-bytestring could just build on top.

[fzhinkin]

@joffrey-bion Are there any existing scenarios where such conversion would make sense? It's not that hard to implement it (#384), but it's unclear if there's an actual demand in requested functionality.

[joffrey-bion]

Yes, those issues are not hypothetical cases. I needed them in my stomp library (Krossbow), to bridge web socket implementations in different platforms. I need to convert to and from ByteString to different platform-specific types.

In this case, it's NSData. I don't think it's that easy to implement correctly. I have a lot of experience with Kotlin, but I'm not very familiar with Kotlin/native development and it wasn't trivial to put the pieces together for me.

Also, it requires relying on unsafe access to avoid copying multiple times, which AFAIU we want to discourage in user code, which makes this kind of APIs more necessary in the library itself.

On the other hand, it doesn't look like a heavy maintenance burden. It seems to be pretty standard API, hence why I believe it makes sense to add it here.

[JakeWharton]

Note that if unsafe were not meant for libraries it would not be a public API.

I'm supportive of these being added, but the need to use unsafe to achieve zero copy should always be true and should not be an impediment for usage in a library.