Add `ByteString.wrap(ByteArray)` for zero-copy creation when ownership is transferred

[MohammedKHC]

ByteArray.toByteString() always copies the array to preserve ByteString's
immutability guarantee. However, there are cases where the caller creates a
ByteArray solely to wrap it in a ByteString and never retains a reference to
it afterwards — making the copy unnecessary.

Example

// KeyFactory returns a new ByteArray — copy in toByteString() is wasteful!
val encoded = key.encoded.toByteString()

Proposed API

// Caller transfers ownership — no copy needed
val bs = ByteString.wrap(key.encoded)

Similar to Java's ByteBuffer.wrap(). The method name makes the
ownership transfer explicit and distinguishes it from the safe toByteString().

[JakeWharton]

Related #1485

I really like the way kotlinx.io does this with its Unsafe* types and an opt-in API.

[MohammedKHC]

Agreed that the kotlinx.io approach is worth referencing,
but UnsafeByteStringOperations is really verbose and the wrapper-object pattern isn't very idiomatic Kotlin — there's even an open issue questioning it, and the usage is quite common in practice which makes the ergonomics hurt even more.

A plain @OptIn-gated function feels like the sweet spot to me — the danger is explicit at the call site without the ceremony:

@RequiresOptIn(
    message = "The caller must guarantee that the ByteArray is not modified after wrapping.",
    level = RequiresOptIn.Level.WARNING
)
annotation class UnsafeByteStringApi

@UnsafeByteStringApi
fun ByteString.Companion.wrap(array: ByteArray): ByteString = ByteString(array)

What do you think?

[JakeWharton]

In my experience, in normal codebases, most people just autocomplete functions and alt+enter the opt-in away without even considering it. Something like this is probably too risky to allow that. We already have the same precedent as kotlinx.io with UnsafeCursor.