ByteString Operations

/**
 * Creates an empty ByteString
 */
val EMPTY: ByteString

/**
 * Creates a ByteString from individual bytes
 * @param data Variable number of bytes
 * @return ByteString containing the specified bytes
 */
fun of(vararg data: Byte): ByteString

/**
 * Encodes a String to ByteString using UTF-8
 * @return ByteString containing UTF-8 encoded bytes
 */
fun String.encodeUtf8(): ByteString

/**
 * Creates a ByteString from a byte array
 * @param offset Starting position in the array (default: 0)
 * @param byteCount Number of bytes to copy (default: entire array)
 * @return ByteString containing copied bytes
 */
fun ByteArray.toByteString(offset: Int = 0, byteCount: Int = size): ByteString

/**
 * Decodes a Base64 string to ByteString
 * @return ByteString containing decoded bytes, or null if invalid Base64
 */
fun String.decodeBase64(): ByteString?

/**
 * Decodes a hexadecimal string to ByteString
 * @return ByteString containing decoded bytes
 * @throws IllegalArgumentException if not valid hex
 */
fun String.decodeHex(): ByteString

// From String
val text = "Hello, World!".encodeUtf8()

// From bytes
val bytes = ByteString.of(72, 101, 108, 108, 111) // "Hello"

// From byte array
val array = byteArrayOf(1, 2, 3, 4, 5)
val byteString = array.toByteString()

// From Base64
val decoded = "SGVsbG8gV29ybGQ=".decodeBase64()

// From hexadecimal
val fromHex = "48656c6c6f".decodeHex() // "Hello"

/**
 * Number of bytes in this ByteString
 */
abstract val size: Int

/**
 * Returns the byte at the specified index
 * @param index Position of the byte (0-based)
 * @return Byte at the specified position
 * @throws IndexOutOfBoundsException if index is out of range
 */
abstract operator fun get(index: Int): Byte

/**
 * Copies bytes to the destination array
 * @param offset Starting position in this ByteString
 * @param target Destination byte array
 * @param targetOffset Starting position in target array
 * @param byteCount Number of bytes to copy
 */
fun copyInto(
    offset: Int,
    target: ByteArray,
    targetOffset: Int,
    byteCount: Int
)

/**
 * Returns a copy of this ByteString as a byte array
 * @return New byte array containing all bytes
 */
abstract fun toByteArray(): ByteArray

val bytes = "Hello".encodeUtf8()
println(bytes.size) // 5
println(bytes[0]) // 72 (ASCII 'H')

val array = bytes.toByteArray()
val copy = ByteArray(3)
bytes.copyInto(1, copy, 0, 3) // Copy "ell" to copy array

/**
 * Decodes this ByteString as UTF-8
 * @return String representation of the UTF-8 bytes
 * @throws IllegalArgumentException if bytes are not valid UTF-8
 */
abstract fun utf8(): String

/**
 * Encodes this ByteString as Base64
 * @return Base64 string representation
 */
abstract fun base64(): String

/**
 * Encodes this ByteString as URL-safe Base64
 * @return URL-safe Base64 string representation
 */
abstract fun base64Url(): String

/**
 * Encodes this ByteString as hexadecimal
 * @return Hexadecimal string representation (lowercase)
 */
abstract fun hex(): String

val bytes = "Hello, World!".encodeUtf8()

println(bytes.utf8())      // "Hello, World!"
println(bytes.base64())    // "SGVsbG8sIFdvcmxkIQ=="
println(bytes.base64Url()) // "SGVsbG8sIFdvcmxkIQ=="
println(bytes.hex())       // "48656c6c6f2c20576f726c6421"

/**
 * Computes MD5 hash (deprecated, use sha256 instead)
 * @return ByteString containing MD5 hash
 */
abstract fun md5(): ByteString

/**
 * Computes SHA-1 hash (deprecated, use sha256 instead)
 * @return ByteString containing SHA-1 hash
 */
abstract fun sha1(): ByteString

/**
 * Computes SHA-256 hash
 * @return ByteString containing SHA-256 hash
 */
abstract fun sha256(): ByteString

/**
 * Computes SHA-512 hash
 * @return ByteString containing SHA-512 hash
 */
abstract fun sha512(): ByteString

/**
 * Computes HMAC-SHA1 with the given key (deprecated)
 * @param key Secret key for HMAC computation
 * @return ByteString containing HMAC-SHA1
 */
@Deprecated("Use hmacSha256 instead")
abstract fun hmacSha1(key: ByteString): ByteString

/**
 * Computes HMAC-SHA256 with the given key
 * @param key Secret key for HMAC computation
 * @return ByteString containing HMAC-SHA256
 */
abstract fun hmacSha256(key: ByteString): ByteString

/**
 * Computes HMAC-SHA512 with the given key  
 * @param key Secret key for HMAC computation
 * @return ByteString containing HMAC-SHA512
 */
abstract fun hmacSha512(key: ByteString): ByteString

val data = "Hello, World!".encodeUtf8()
val key = "secret-key".encodeUtf8()

val sha256Hash = data.sha256()
println(sha256Hash.hex())

val hmac = data.hmacSha256(key)
println(hmac.hex())

/**
 * Returns a ByteString with ASCII characters converted to lowercase
 * @return New ByteString with lowercase ASCII characters
 */
abstract fun toAsciiLowercase(): ByteString

/**
 * Returns a ByteString with ASCII characters converted to uppercase
 * @return New ByteString with uppercase ASCII characters
 */
abstract fun toAsciiUppercase(): ByteString

/**
 * Returns a substring of this ByteString
 * @param beginIndex Starting index (inclusive)
 * @param endIndex Ending index (exclusive, default: size)
 * @return New ByteString containing the specified range
 */
fun substring(beginIndex: Int, endIndex: Int = size): ByteString

val text = "Hello, World!".encodeUtf8()

val lower = text.toAsciiLowercase()
println(lower.utf8()) // "hello, world!"

val upper = text.toAsciiUppercase()  
println(upper.utf8()) // "HELLO, WORLD!"

val hello = text.substring(0, 5)
println(hello.utf8()) // "Hello"

/**
 * Finds the first occurrence of the specified ByteString
 * @param byteString ByteString to search for
 * @param fromIndex Starting search index (default: 0)
 * @return Index of first occurrence, or -1 if not found
 */
fun indexOf(byteString: ByteString, fromIndex: Int = 0): Int

/**
 * Finds the last occurrence of the specified ByteString  
 * @param byteString ByteString to search for
 * @return Index of last occurrence, or -1 if not found
 */
fun lastIndexOf(byteString: ByteString): Int

/**
 * Checks if this ByteString starts with the specified prefix
 * @param prefix ByteString to check for
 * @return true if this starts with prefix
 */
fun startsWith(prefix: ByteString): Boolean

/**
 * Checks if this ByteString ends with the specified suffix
 * @param suffix ByteString to check for  
 * @return true if this ends with suffix
 */
fun endsWith(suffix: ByteString): Boolean

/**
 * Compares a range of this ByteString with another ByteString
 * @param offset Starting position in this ByteString
 * @param other ByteString to compare with
 * @param otherOffset Starting position in other ByteString
 * @param byteCount Number of bytes to compare
 * @return true if the specified ranges are equal
 */
fun rangeEquals(
    offset: Int,
    other: ByteString,
    otherOffset: Int,
    byteCount: Int
): Boolean

val text = "Hello, World!".encodeUtf8()
val search = "World".encodeUtf8()

val index = text.indexOf(search)
println(index) // 7

val hasHello = text.startsWith("Hello".encodeUtf8())
println(hasHello) // true

val hasExclamation = text.endsWith("!".encodeUtf8())
println(hasExclamation) // true