• Indexing
• String Building
• Methods

A byte buffer, buf, is a dynamic array of bytes.

$buf() -> buf
$buf(content: str) -> buf
$buf(size: i64, fill_value: i64|rune) -> buf

Creates a new byte buffer.

• If called with zero arguments, creates a new empty buffer.
• If called with a single string argument, creates a new buffer containing a copy of the string's bytes.
• If called with two arguments, creates a new buffer with the specified initial size and fill value, where size is a positive integer and value is an integer value in the range [0, 255].

Indexing

You can index into a buffer to get or set byte values, e.g.

var buf = $buf("foobar");
assert buf[0] == 102;
assert buf[1] == 111;

buf[0] = 99;
assert buf[0] == 99;
assert $str(buf) == "coobar";

Indices are zero-based. A negative index counts backwards from the end of the buffer, e.g.

var buf = $buf("foobar");
assert buf[-1] == 'r';
assert buf[-2] == 'a';
assert buf[-3] == 'b';

Indexing is equivalent to using the buffer's :get() and :set() methods, e.g.

var buf = $buf("foobar");
assert buf:get(0) == 102;
assert buf:get(1) == 111;

buf:set(0, 99);
assert buf:get(0) == 99;
assert $str(buf) == "coobar";

Indexing into a buffer will panic if the index is out-of-range, e.g.

var buf = $buf("foobar");
assert $is_err(try buf[123]);

String Building

Writing to a buffer and then converting it to a string is an efficient way of assembling a long string from multiple parts as it avoids the overhead of creating temporary strings along the way, e.g.

var buf = $buf();
buf:write("foo");
buf:write("bar");

var result = buf:to_str();
assert result == "foobar";
assert buf:is_empty();

Calling the buffer's :to_str() method converts its content into a string, leaving a valid but empty buffer object behind.

(This is different from calling $str(buf) on a buffer, which returns a string contining a copy of the buffer's content, leaving the buffer itself unchanged.)

Methods

:as_hex() -> str

Returns a copy of the buffer's content as a hex-escaped string, leaving the buffer itself unchanged.

:as_str() -> str

Returns a copy of the buffer's content as a string, leaving the buffer itself unchanged.

:byte(index: i64) -> i64

Returns the byte value at index as an integer in the range [0, 255].

A negative index counts backwards from the end of the buffer.

(This method is an alias for :get(). It's defined so buffers and strings expose a common interface for addressing byte values.)

:clear()

Clears the buffer.

:contains(target: buf|str) -> bool

Returns true if the buffer contains target.

:count() -> i64

Returns the number of bytes in the buffer.

:get(index: i64) -> i64

Returns the byte value at index as an integer in the range [0, 255].

A negative index counts backwards from the end of the buffer.

:is_empty() -> bool

Returns true if the buffer is empty.

:match(target: buf|str, index: i64) -> bool

Returns true if target matches at byte index index.

:resize(new_size: i64, fill_value: i64|rune = 0)

Resizes the buffer.

• If new_size is negative, it will be interpreted as a number of bytes to trim from the end of the buffer.
• If new_size is positive and smaller than the current buffer size, the buffer will be truncated to new_size bytes.
• If new_size is positive and bigger than the current buffer size, the buffer will be extended to new_size bytes by appending fill_value, which must be an integer in the range [0, 255].

:set(index: i64, value: i64|rune)

Sets the byte value at index to value, where value is an integer in the range [0, 255].

A negative index counts backwards from the end of the buffer.

:slice(start_index: i64) -> buf
:slice(start_index: i64, length: i64) -> buf

Copies a slice of the source buffer and returns it as a new buffer. The source buffer is left unchanged. The slice starts at byte index start_index and contains length bytes.

If start_index is negative, counts backwards from the end of the buffer — i.e. a start_index of -1 refers to to the last byte in the buffer.

If length is omitted, copies to the end of the source buffer.

Panics if either argument is out of range.

:to_str() -> str

Converts the content of the buffer into a string, leaving a valid but empty buffer object behind. Returns the new string.

:write(arg: any) -> i64
:write(format_string: str, *args: any) -> i64

Appends the content of a string or buffer to the buffer.

• If arg is a str or buf, its content will be written to the buffer directly.
• Otherwise, calling this method with a single argument is equivalent to calling $str() on that argument first and writing the resulting string.
• Calling this method with more than one argument is equivalent to calling $fmt() on those arguments first and writing the resulting string.

Returns the number of bytes written to the buffer.

:write_byte(byte: i64|rune)

Appends byte to the buffer where byte is an integer in the range [0, 255]. Will panic if byte is not an integer or is out of range.