Buffer Operations

/**
 * Creates a new empty Buffer
 */
class Buffer() : BufferedSource, BufferedSink

/**
 * Number of bytes currently in the buffer
 */
val size: Long

/**
 * Removes all bytes from the buffer
 */
fun clear()

/**
 * Creates a deep copy of this buffer
 * @return New Buffer with identical content
 */
fun copy(): Buffer

/**
 * Creates an immutable snapshot of the current buffer content
 * @return ByteString containing current buffer bytes
 */
fun snapshot(): ByteString

/**
 * Returns the number of bytes in completed segments
 * Used for efficient bulk operations
 * @return Number of bytes in full segments
 */
fun completeSegmentByteCount(): Long

val buffer = Buffer()
buffer.writeUtf8("Hello")
println(buffer.size) // 5

val copy = buffer.copy()
val snapshot = buffer.snapshot()
println(snapshot.utf8()) // "Hello"

buffer.clear()
println(buffer.size) // 0

/**
 * Checks if the buffer is exhausted (empty)
 * @return true if no more bytes are available
 */
fun exhausted(): Boolean

/**
 * Ensures at least byteCount bytes are available for reading
 * @param byteCount Minimum number of bytes required
 * @throws EOFException if insufficient bytes available
 */
fun require(byteCount: Long)

/**
 * Requests that at least byteCount bytes are available
 * @param byteCount Number of bytes requested
 * @return true if the requested bytes are available
 */
fun request(byteCount: Long): Boolean

/**
 * Reads and removes a single byte
 * @return The byte value (0-255)
 * @throws EOFException if buffer is empty
 */
fun readByte(): Byte

/**
 * Reads and removes a 16-bit integer in big-endian format
 * @return Short value
 * @throws EOFException if insufficient bytes
 */
fun readShort(): Short

/**
 * Reads and removes a 16-bit integer in little-endian format
 * @return Short value
 * @throws EOFException if insufficient bytes
 */
fun readShortLe(): Short

/**
 * Reads and removes a 32-bit integer in big-endian format
 * @return Int value
 * @throws EOFException if insufficient bytes
 */
fun readInt(): Int

/**
 * Reads and removes a 32-bit integer in little-endian format
 * @return Int value
 * @throws EOFException if insufficient bytes
 */
fun readIntLe(): Int

/**
 * Reads and removes a 64-bit integer in big-endian format
 * @return Long value
 * @throws EOFException if insufficient bytes
 */
fun readLong(): Long

/**
 * Reads and removes a 64-bit integer in little-endian format
 * @return Long value
 * @throws EOFException if insufficient bytes
 */
fun readLongLe(): Long

/**
 * Reads all remaining bytes as UTF-8 string
 * @return String representation of all bytes
 */
fun readUtf8(): String

/**
 * Reads the specified number of bytes as UTF-8 string
 * @param byteCount Number of bytes to read
 * @return String representation of the bytes
 * @throws EOFException if insufficient bytes
 */
fun readUtf8(byteCount: Long): String

/**
 * Reads all remaining bytes as ByteString
 * @return ByteString containing all bytes
 */
fun readByteString(): ByteString

/**
 * Reads the specified number of bytes as ByteString
 * @param byteCount Number of bytes to read
 * @return ByteString containing the bytes
 * @throws EOFException if insufficient bytes
 */
fun readByteString(byteCount: Long): ByteString

val buffer = Buffer()
buffer.writeUtf8("Hello")
buffer.writeInt(42)

println(buffer.readUtf8(5)) // "Hello"
println(buffer.readInt())   // 42
println(buffer.exhausted()) // true

/**
 * Writes a single byte to the buffer
 * @param b Byte value to write
 * @return This buffer for chaining
 */
fun writeByte(b: Int): Buffer

/**
 * Writes a 16-bit integer in big-endian format
 * @param s Short value to write
 * @return This buffer for chaining
 */
fun writeShort(s: Int): Buffer

/**
 * Writes a 16-bit integer in little-endian format
 * @param s Short value to write
 * @return This buffer for chaining
 */
fun writeShortLe(s: Int): Buffer

/**
 * Writes a 32-bit integer in big-endian format
 * @param i Int value to write
 * @return This buffer for chaining
 */
fun writeInt(i: Int): Buffer

/**
 * Writes a 32-bit integer in little-endian format
 * @param i Int value to write
 * @return This buffer for chaining
 */
fun writeIntLe(i: Int): Buffer

/**
 * Writes a 64-bit integer in big-endian format
 * @param v Long value to write
 * @return This buffer for chaining
 */
fun writeLong(v: Long): Buffer

/**
 * Writes a 64-bit integer in little-endian format
 * @param v Long value to write
 * @return This buffer for chaining
 */
fun writeLongLe(v: Long): Buffer

/**
 * Writes a string as UTF-8 bytes
 * @param string String to write
 * @return This buffer for chaining
 */
fun writeUtf8(string: String): Buffer

/**
 * Writes a portion of a string as UTF-8 bytes
 * @param string String to write
 * @param beginIndex Starting character index
 * @param endIndex Ending character index
 * @return This buffer for chaining
 */
fun writeUtf8(string: String, beginIndex: Int, endIndex: Int): Buffer

/**
 * Writes all bytes from a ByteString
 * @param byteString ByteString to write
 * @return This buffer for chaining
 */
fun write(byteString: ByteString): Buffer

/**
 * Writes all bytes from a byte array
 * @param source Byte array to write
 * @return This buffer for chaining
 */
fun write(source: ByteArray): Buffer

/**
 * Writes bytes from a byte array
 * @param source Byte array to write from
 * @param offset Starting position in source array
 * @param byteCount Number of bytes to write
 * @return This buffer for chaining
 */
fun write(source: ByteArray, offset: Int, byteCount: Int): Buffer

val buffer = Buffer()
    .writeUtf8("Hello")
    .writeByte(32) // space
    .writeUtf8("World")
    .writeByte(33) // exclamation

println(buffer.readUtf8()) // "Hello World!"

// Write binary data
val data = Buffer()
    .writeInt(42)
    .writeLong(123456789L)
    .writeShortLe(0x1234)

/**
 * Returns the byte at the specified position without removing it
 * @param pos Position of the byte (0-based)
 * @return Byte at the specified position
 * @throws IndexOutOfBoundsException if pos is out of range
 */
operator fun get(pos: Long): Byte

/**
 * Copies data to another buffer
 * @param out Destination buffer
 * @param offset Starting position in this buffer
 * @param byteCount Number of bytes to copy
 * @return This buffer for chaining
 */
fun copyTo(out: Buffer, offset: Long = 0, byteCount: Long = size - offset): Buffer

/**
 * Provides unsafe cursor access to internal segments
 * @return UnsafeCursor for direct segment access
 */
fun readUnsafe(): Buffer.UnsafeCursor

/**
 * Provides unsafe cursor access for both reading and writing
 * @return UnsafeCursor for direct segment access
 */
fun readAndWriteUnsafe(): Buffer.UnsafeCursor

val buffer = Buffer()
buffer.writeUtf8("Hello World")

// Direct access
println(buffer[0]) // 72 (ASCII 'H')
println(buffer[6]) // 87 (ASCII 'W')

// Copy to another buffer
val copy = Buffer()
buffer.copyTo(copy, 0, 5) // Copy "Hello"
println(copy.readUtf8()) // "Hello"

/**
 * Computes MD5 hash of buffer content (deprecated)
 * @return ByteString containing MD5 hash
 */
fun md5(): ByteString

/**
 * Computes SHA-1 hash of buffer content
 * @return ByteString containing SHA-1 hash
 */
fun sha1(): ByteString

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

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

/**
 * Computes HMAC-SHA1 of buffer content
 * @param key Secret key for HMAC computation
 * @return ByteString containing HMAC-SHA1
 */
fun hmacSha1(key: ByteString): ByteString

/**
 * Computes HMAC-SHA256 of buffer content
 * @param key Secret key for HMAC computation
 * @return ByteString containing HMAC-SHA256
 */
fun hmacSha256(key: ByteString): ByteString

/**
 * Computes HMAC-SHA512 of buffer content
 * @param key Secret key for HMAC computation
 * @return ByteString containing HMAC-SHA512
 */
fun hmacSha512(key: ByteString): ByteString

val buffer = Buffer()
buffer.writeUtf8("Hello, World!")

val sha256 = buffer.sha256()
println(sha256.hex())

val key = "secret".encodeUtf8()
val hmac = buffer.hmacSha256(key)
println(hmac.hex())

/**
 * Cursor for direct access to buffer segments
 * Provides unsafe but efficient access to internal byte arrays
 */
class UnsafeCursor {
    /**
     * Current segment's byte array, or null if at end
     */
    var data: ByteArray?
    
    /**
     * Starting index in current segment's byte array
     */
    var start: Int
    
    /**
     * Ending index in current segment's byte array
     */
    var end: Int
    
    /**
     * Current position in the buffer
     */
    var offset: Long
    
    /**
     * Moves cursor to the specified position
     * @param offset Target position in buffer
     * @return Number of bytes available from this position
     */
    fun seek(offset: Long): Long
    
    /**
     * Moves cursor to next segment
     * @return Number of bytes in next segment, or -1 if at end
     */
    fun next(): Long
    
    /**
     * Closes the cursor and releases resources
     */
    fun close()
}

val buffer = Buffer()
buffer.writeUtf8("Hello World")

// Read using unsafe cursor
val cursor = buffer.readUnsafe()
cursor.seek(0)
while (cursor.data != null) {
    for (i in cursor.start until cursor.end) {
        print("${cursor.data!![i].toChar()}")
    }
    cursor.next()
}
cursor.close()