lib/buffer.x

Growable text buffer with indentation support.

Primary API

Buffer

Buffer.clear

Self Buffer.clear(Self buf)

Empties buf and its indentation stack without releasing capacity.

Source: lib/buffer.x:105

Buffer.len

size_t Buffer.len(Buffer buf)

Returns the number of bytes currently stored in buf.

Source: lib/buffer.x:311

Buffer.new

Buffer Buffer.new(size_t padding)

Allocates an empty Buffer whose pad method writes padding spaces.

Raises: <alloc-fail> or <size-limit> while allocating its fixed-width backing Blocks.

Source: lib/buffer.x:60

Buffer.pop

Self Buffer.pop(Self buf)

Pops one indentation depth from buf’s stack when present.

Source: lib/buffer.x:269

Buffer.push

Self Buffer.push(Self buf)

Pushes the current column as a later indentation depth.

Raises: <size-limit> or <alloc-fail> if the stack cannot grow. Failure leaves the stack unchanged.

Source: lib/buffer.x:263

Buffer.truth

int Buffer.truth(Buffer buffer)

Returns nonzero when buffer contains at least one byte.

Source: lib/buffer.x:350

Buffer.try_get

int Buffer.try_get(Buffer buf, ptrdiff_t index, char *out)

Writes the byte at normalized index to out when it exists. Negative indexes count from the end. Returns zero for a null Buffer, null output, or missing byte and leaves out unchanged.

Source: lib/buffer.x:285

Advanced and interop API

Buffer

Buffer.free

void Buffer.free(Buffer buf)

Releases buf and both backing Blocks, invalidating every alias.

Source: lib/buffer.x:73

Buffer.indent

Self Buffer.indent(Self buf)

Appends spaces through buf’s current indentation depth.

Source: lib/buffer.x:254

Buffer.newline

Self Buffer.newline(Self buf)

Appends a newline to buf.

Source: lib/buffer.x:251

Buffer.newline_indent

Self Buffer.newline_indent(Self buf)

Appends a newline followed by current indentation.

Source: lib/buffer.x:257

Buffer.pad

Self Buffer.pad(Self buf)

Appends the configured number of padding spaces.

Source: lib/buffer.x:248

Buffer.printf

Self Buffer.printf(Self buf, const char *format, ...)

Appends formatted text to buffer.

Raises: <format> when formatting fails, <alloc-fail> when staging storage cannot be allocated, or a cause from Buffer.write_len. Existing text is preserved and this call appends nothing on failure.

Source: lib/buffer.x:180

Buffer.repr

String Buffer.repr(Buffer buf)

Returns the readable representation of Buffer.

Raises: the same causes as Buffer.str or String rendering.

Source: lib/buffer.x:343

Buffer.reserve

Self Buffer.reserve(Self buf, size_t minimum)

Reserves room for at least minimum output bytes in buf. Growth may invalidate a borrowed content.bytes pointer but does not change the Buffer or content Block identity.

Raises: <size-limit> or <alloc-fail> when the requested capacity cannot be provided.

Source: lib/buffer.x:99

Buffer.str

String Buffer.str(Buffer buf)

Returns a canonical copy of buf’s text without consuming the Buffer. A null or empty Buffer returns the null String. A nonempty result remains live until its owning String pool is released.

Raises: <size-limit> when the text exceeds String’s representation, or <alloc-fail> while canonicalizing it.

Source: lib/buffer.x:320

Buffer.str_free

String Buffer.str_free(Buffer buf)

Returns buf.str() and frees buf. Buffer.str performs the conversion, so the result is a canonical String copied out of the Buffer. Its storage is not adopted. buf is released on success and when the conversion transfers an Error.

Raises: the same causes as Buffer.str.

Source: lib/buffer.x:335

Buffer.tabstop

size_t Buffer.tabstop(Buffer buf)

Returns the most recently pushed indentation depth.

Source: lib/buffer.x:275

Buffer.unwrite

Self Buffer.unwrite(Self buf, size_t count)

Removes the final count bytes from buf.

Source: lib/buffer.x:240

Buffer.write

Self Buffer.write(Self buf, const char *text)

Appends NUL-terminated text to buf.

Raises: the same causes as Buffer.write_len.

Source: lib/buffer.x:170

Buffer.write_char

Self Buffer.write_char(Self buf, char value)

Appends the non-NUL byte value to buf.

Raises: <bad-arg> when value is NUL, or <size-limit> or <alloc-fail> when the Buffer cannot grow. These failures leave text and line state unchanged.

Source: lib/buffer.x:204

Buffer.write_len

Self Buffer.write_len(Self buf, const char *text, size_t length)

Appends length bytes from text to buf. text may be a live range inside buf.content, including across growth. A zero length accepts a null source. Raises: <bad-arg> for a null nonempty source or embedded NUL, or <size-limit> or <alloc-fail> when the Buffer cannot grow. Argument, allocation, and size failures leave the text and line state unchanged.

Source: lib/buffer.x:120

Buffer.write_repeat

Self Buffer.write_repeat(Self buf, char value, size_t count)

Appends count copies of the non-NUL byte value to buf. A zero count accepts any value. Raises: <bad-arg> when a nonzero write uses NUL, or <size-limit> or <alloc-fail> when the Buffer cannot grow. These failures leave text and line state unchanged.

Source: lib/buffer.x:224

Compatibility API

Buffer

Buffer.get

char Buffer.get(Buffer buf, ptrdiff_t index)

Returns the byte at index, or NUL when index is out of range. This adapter is retained for source and ABI compatibility. For new code, prefer Buffer.try_get.

Source: lib/buffer.x:305

Runtime-internal callables

These callables connect runtime translation units. They are documented for source readers but are not supported as user API.

Buffer

Buffer.move_to

void Buffer.move_to(Buffer buf, Scope *scope)

Moves buf and both owned Blocks into scope, keeping their identities. Their lifetime then ends with the destination Scope unless freed earlier. For a nonnull Buffer, raises <bad-arg> for a null destination slot, or <alloc-fail> when an empty slot cannot acquire a Scope. Failure leaves ownership unchanged.

Source: lib/buffer.x:86

Public types

Buffer

typedef struct Buffer { Block content, indents, size_t padding, pos, _indent; } *Buffer

Holds mutable text plus an indentation stack in two Blocks. The Buffer and both Blocks belong to the Scope active at construction unless Buffer.move_to transfers them. content.bytes is a borrowed, non-NUL-terminated view that any growing write may invalidate. pos and _indent describe the current final line; Buffer.free invalidates the Buffer and both backing Blocks.

Source: lib/buffer.x:25

Design notes

Buffer is a text-only builder over Block storage. It tracks the byte position and leading indentation of the current line, supports nested tabstops, and provides bulk character writes for formatting hot paths. Embedded NUL is rejected because Buffer materializes canonical Strings.

Tests and examples

make verify (unittest/test-buffer.x).