`buf`

Byte buffer - a mutable growable byte accumulator backed by host natives. Append strings, individual bytes, or byte lists; read the accumulated content; clear and reuse.

Load with: use buf

What this module does

buf provides a low-level mutable byte buffer. Unlike ilusm strings (which are immutable), a buffer lets you accumulate bytes incrementally without allocating a new string on every append. When you're done, call bufou to read out the accumulated content as a string, or bufcl to reset it for reuse.

The three overloads of bufpu accept a raw string, a single integer byte value (clamped to 0–255 via enc.mod), or a list of integer byte values.

Quick example

use buf

b = bufne()
bufpu(b, "Hello")
bufpu(b, 44)       # byte value for ','
bufpu(b, " world")
prn(bufou(b))      # "Hello, world"

bufcl(b)           # reset for reuse
bufpu(b, [72, 105])  # byte list: "Hi"
prn(bufou(b))      # "Hi"

# Build from a byte list directly
b2 = buffr([65, 66, 67])
prn(bufou(b2))     # "ABC"

Functions

Lifecycle

bufne()

Creates a new empty byte buffer via host native __buf_new.

bufcl(b)

Clears the buffer, resetting it to empty via __buf_clr. The buffer object can then be reused.

Writing

bufpu(b, s) - string

Appends a string s directly to the buffer via __buf_put.

bufpu(b, u) - byte value

Appends a single byte by integer value. Converts with txt.chr(enc.mod(int(u), 256)) - so values outside 0–255 are wrapped modulo 256.

bufpu(b, xs) - byte list

Appends each integer in list xs as a byte. Errors with "bufputlist: need list of byte values" if xs is not a list.

Reading

bufou(b)

Returns the current contents of the buffer as a string via __buf_out. Does not clear the buffer.

Construction helper

buffr(xs)

Creates a new buffer, appends all bytes from the list xs, and returns the buffer. Shorthand for creating a buffer pre-loaded with a byte list.

Notes

All core operations (bufne, bufpu string variant, bufou, bufcl) delegate to host natives documented in docs/SYSCALLS.md.
Byte values are wrapped modulo 256 - passing 300 appends byte 44.
Requires enc and txt.