lib/buffer.x

Growable text buffer with indentation support.

Primary API

Buffer

Buffer.clear

meta native Self Buffer.clear(Self buf)

Empties buf and its indentation stack without releasing capacity.

Source: lib/buffer.x:327

Buffer.getindex

int Buffer.getindex(Buffer buf, int index)

Returns buf.get(index), so buf[index] reads a byte.

Source: lib/buffer.x:255

Buffer.len

size_t Buffer.len(Buffer buf)

Returns the number of bytes currently stored in buf.

Source: lib/buffer.x:258

Buffer.new

meta native 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:304

Buffer.pop

meta native Self Buffer.pop(Self buf)

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

Source: lib/buffer.x:213

Buffer.push

meta native 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:207

Buffer.truth

int Buffer.truth(Buffer b)

Returns nonzero when b contains at least one byte.

Source: lib/buffer.x:296

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

Advanced and interop API

Buffer

Buffer.cleanup

void Buffer.cleanup(Buffer value)

Ends the owned lifetime when a managed local leaves its block.

Source: lib/buffer.x:30

Buffer.free

void Buffer.free(Buffer buf)

Releases buf and both backing Blocks, invalidating every alias.

Source: lib/buffer.x:348

Buffer.indent

meta native Self Buffer.indent(Self buf)

Appends spaces through buf’s current indentation depth.

Source: lib/buffer.x:197

Buffer.newline

meta native Self Buffer.newline(Self buf)

Appends a newline to buf.

Source: lib/buffer.x:194

Buffer.newline_indent

meta native Self Buffer.newline_indent(Self buf)

Appends a newline followed by current indentation.

Source: lib/buffer.x:201

Buffer.pad

meta native Self Buffer.pad(Self buf)

Appends the configured number of padding spaces.

Source: lib/buffer.x:191

Buffer.printf

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

Appends formatted text to buf.

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

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

Buffer.reserve

meta native 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:321

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

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

Buffer.tabstop

size_t Buffer.tabstop(Buffer buf)

Returns the indentation depth on top of the stack, or 0 when empty.

Source: lib/buffer.x:219

Buffer.unwrite

meta native Self Buffer.unwrite(Self buf, size_t count)

Removes the final count bytes from buf.

Source: lib/buffer.x:129

Buffer.write

meta native 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:71

Buffer.write_char

meta native 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:104

Buffer.write_len

meta native 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:54

Buffer.write_repeat

meta native 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:120

Convenience 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. Prefer Buffer.try_get to distinguish an out-of-range index from a NUL byte.

Source: lib/buffer.x:249

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

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

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