• 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. 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_str() -> str

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

:clear()

Clears the buffer.

: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].

• Panics if index isn't an integer or is out of range.

:is_empty() -> bool

Returns true if the buffer is empty.

: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].

• Panics if index isn't an integer or is out of range.
• Panics if value isn't an integer or 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.

This method will panic if an error occurs while formatting the string or if memory allocation fails.

: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.