Buffer Module

The std/buffer module provides a Buffer class for working with raw binary data. Buffers are essential for implementing binary protocols, parsing file formats, and performing low-level I/O operations.

Import

import { Buffer } from "std/buffer"

Creating Buffers

Buffer.alloc(size: int): Buffer

Allocates a new zero-filled buffer of the given size in bytes.

var buf = Buffer.alloc(256)
println(buf.length()) // 256

Buffer.fromString(s: string): Buffer

Creates a buffer from a UTF-8 encoded string.

var buf = Buffer.fromString("Hello, Chuks!")
println(buf.length()) // 13
println(buf.toString("utf8")) // "Hello, Chuks!"

Buffer.fromArray(arr: []int): Buffer

Creates a buffer from an array of byte values (0–255).

var buf = Buffer.fromArray([72, 101, 108, 108, 111])
println(buf.toString("utf8")) // "Hello"

Buffer.fromHex(hexString: string): Buffer

Creates a buffer from a hex-encoded string. Each pair of hex characters becomes one byte. Useful for converting hex-encoded hashes or crypto outputs back to raw bytes.

var buf = Buffer.fromHex("48656c6c6f")
println(buf.toString("utf8")) // "Hello"
println(buf.length())         // 5

// Convert a SHA-256 hex digest back to raw bytes
var hashHex = crypto.sha256("data")
var hashBuf = Buffer.fromHex(hashHex)

Buffer.concat(buffers: []any): Buffer

Concatenates multiple buffers into a single new buffer.

var a = Buffer.fromString("Hello ")
var b = Buffer.fromString("World")
var combined = Buffer.concat([a, b])
println(combined.toString("utf8")) // "Hello World"

new Buffer(size: int)

Constructor — allocates a zero-filled buffer of the given size.

var buf = new Buffer(64)

Reading & Writing Integers

All integer read/write methods use big-endian byte order and advance the internal cursor automatically.

Unsigned Integers

var buf = Buffer.alloc(16)

// Write
buf.writeUInt8(255)      // 1 byte
buf.writeUInt16BE(65535) // 2 bytes
buf.writeUInt32BE(1000)  // 4 bytes

// Reset cursor and read back
buf.reset()
println(buf.readUInt8())    // 255
println(buf.readUInt16BE()) // 65535
println(buf.readUInt32BE()) // 1000

Signed Integers

var buf = Buffer.alloc(16)

buf.writeInt8(-42)
buf.writeInt16BE(-1234)
buf.writeInt32BE(305419896)
buf.writeInt64BE(1234567890123)

buf.reset()
println(buf.readInt8())    // -42
println(buf.readInt16BE()) // -1234
println(buf.readInt32BE()) // 305419896
println(buf.readInt64BE()) // 1234567890123

Floating-Point Numbers

var buf = Buffer.alloc(12)

buf.writeFloat32BE(3.14)
buf.writeFloat64BE(2.718281828)

buf.reset()
println(buf.readFloat32BE()) // ~3.14
println(buf.readFloat64BE()) // 2.718281828

Reading & Writing Strings

writeString(s: string): void

Writes a UTF-8 string into the buffer at the current cursor position.

var buf = Buffer.alloc(64)
buf.writeString("hello world")

readString(length: int): string

Reads length bytes from the current cursor position as a UTF-8 string.

buf.reset()
var s = buf.readString(5) // "hello"

writeNullTerminated(s: string): void

Writes a string followed by a null byte (\0). Used in many C-style protocols.

buf.writeNullTerminated("username")

readNullTerminated(): string

Reads bytes until a null byte is found, returning the string.

buf.reset()
var username = buf.readNullTerminated() // "username"

Cursor Management

The buffer maintains an internal read/write cursor that advances automatically.

getOffset(): int

Returns the current cursor position.

seek(position: int): void

Sets the cursor to an absolute position.

reset(): void

Resets the cursor to position 0.

remaining(): int

Returns the number of bytes between the cursor and the end of the buffer.

var buf = Buffer.alloc(100)
buf.writeUInt32BE(42)
println(buf.getOffset())  // 4
println(buf.remaining())  // 96
buf.reset()
println(buf.getOffset())  // 0

Direct Byte Access

getByte(index: int): int

Returns the byte value at the given index (does not move the cursor).

setByte(index: int, value: int): void

Sets the byte value at the given index (does not move the cursor).

var buf = Buffer.alloc(4)
buf.setByte(0, 0xFF)
buf.setByte(1, 0x42)
println(buf.getByte(0)) // 255
println(buf.getByte(1)) // 66

Buffer Operations

slice(start: int, end: int): Buffer

Returns a new buffer containing bytes from start to end (exclusive).

var buf = Buffer.fromString("Hello World")
var hello = buf.slice(0, 5)
println(hello.toString("utf8")) // "Hello"

copy(source: Buffer, destOffset: int, srcOffset: int, length: int): void

Copies length bytes from source into this buffer.

fill(value: int): void

Fills the entire buffer with the given byte value.

fillRange(value: int, start: int, end: int): void

Fills a range of the buffer with the given byte value.

var buf = Buffer.alloc(10)
buf.fill(0xFF)         // fill all with 255
buf.fillRange(0, 2, 8) // zero out bytes 2-7

indexOf(value: int): int

Returns the index of the first occurrence of the byte value, or -1.

indexOfFrom(value: int, start: int): int

Same as indexOf but starts searching from the given position.

equals(other: Buffer): bool

Returns true if this buffer has the same contents as other.

xor(other: Buffer): Buffer

Returns a new buffer that is the XOR of the two buffers (must be same length).

var a = Buffer.fromArray([0x00, 0xFF, 0xAA])
var b = Buffer.fromArray([0xFF, 0x00, 0x55])
var result = a.xor(b).toArray()
println(result) // [255, 255, 255]

Conversion Methods

toString(encoding: string): string

Converts the buffer to a string. Supported encodings: "utf8", "hex".

var buf = Buffer.fromString("Hello")
println(buf.toString("utf8")) // "Hello"
println(buf.toString("hex"))  // "48656c6c6f"

toStringUtf8(): string

Convenience method — same as toString("utf8").

toArray(): []int

Returns the buffer contents as an array of byte values.

var buf = Buffer.fromString("Hi")
println(buf.toArray()) // [72, 105]

length(): int

Returns the length of the buffer in bytes.

capacity(): int

Returns the allocated capacity (may be larger than length after grows).

Writing Raw Bytes

writeBytes(source: Buffer, length: int): void

Writes length bytes from the source buffer into this buffer.

writeBytesAll(source: Buffer): void

Writes the entire contents of the source buffer.

readBytes(length: int): Buffer

Reads length bytes from the current position and returns a new buffer.

Complete Example: Building a Binary Message

import { Buffer } from "std/buffer"

// Build a simple message: [type:u8][length:u32][payload:string]
function encodeMessage(msgType: int, payload: string): Buffer {
    var payloadBuf = Buffer.fromString(payload)
    var buf = Buffer.alloc(5 + payloadBuf.length())
    buf.writeUInt8(msgType)
    buf.writeUInt32BE(payloadBuf.length())
    buf.writeBytesAll(payloadBuf)
    return buf
}

function decodeMessage(buf: Buffer): map[string]any {
    buf.reset()
    var msgType = buf.readUInt8()
    var length = buf.readUInt32BE()
    var payload = buf.readString(length)
    return {"type": msgType, "payload": payload}
}

var msg = encodeMessage(1, "Hello, Protocol!")
var decoded = decodeMessage(msg)
println(decoded["type"])    // 1
println(decoded["payload"]) // "Hello, Protocol!"