• 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|char) -> buf

Creates a new buf object.

• 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";

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.

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

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

Calling the :to_str() method converts the content of the buffer 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

: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]. Will panic if index isn't an integer or is out of range.

:is_empty() -> bool

Returns true if the buffer is empty.

:set(index: i64, byte: i64|char)

Sets the byte value at index to byte where byte is an integer in the range [0, 255]. Will panic if index isn't an integer or is out of range. Will panic if byte 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.

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 cost of creating multiple temporary strings along the way.

Note that calling $str(buf) on a buffer does something different — it creates a string with a copy of the buffer's content, leaving the buffer itself unchanged.

: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|char)

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.