Formatting

The f-string lowering target and formatting buffers.

`FmtBuf`

class FmtBuf

The buffer an f-string is built in. FStringLowering turns f"a {x} b" into one FmtBuf and a call per part (text, put_*), then finish(); users can also keep one to format into repeatedly.

Up to 127 bytes live inside the object; longer text spills to the heap (from the allocator in effect, the same one string uses). Not copyable or movable: data points into the object.

Every put_* takes a spec, a packed u64 format spec (width, precision, fill, alignment, base, flags; layout in the file header). 0 means defaults.

Example

var b = FmtBuf()
b.write(f"x = {42}")
var s = b.view()

`FmtBuf.data`

var data: *u8

Pointer to the bytes: the inline storage until the first spill, then the heap block. Null after finish().

`FmtBuf.len`

var len: usize

Bytes written so far.

`FmtBuf.cp_len`

var cp_len: usize

Codepoints written so far (what the finished string's codepoints() reports).

`FmtBuf.cap`

var cap: usize

Usable bytes before the next growth; the block has cap + 1 bytes for the NUL.

`FmtBuf.FmtBuf`

fn FmtBuf(self, cap: usize)

Creates a buffer bounded to cap bytes, as the lowering does with a compile-time bound.

Below 128 it uses the inline storage (growing to the heap only if the text outgrows it); from 128 up the heap block is allocated now, sized once.

`FmtBuf.FmtBuf`

fn FmtBuf(self)

Creates an empty buffer on its inline storage, for formatting repeatedly (var b = FmtBuf()).

`FmtBuf.reserve`

inline fn reserve(self, n: usize)

Room for n more bytes, so the puts that follow never grow. Ensures room for n more bytes, so the puts that follow do not grow.

`FmtBuf.write`

inline fn write(self, const s: string)

Appends s as {s} would.

b.write(f"...") never calls this: the lowering writes the f-string's parts straight onto b.

`FmtBuf.text`

inline fn text(self, p: *const u8, n: usize, cp: usize)

Appends n literal bytes at p that encode cp codepoints. Both counts are trusted, not checked (constants at every lowered call site).

`FmtBuf.put_str`

inline fn put_str(self, const s: string, spec: u64)

Appends a string hole. With spec == 0 the string is copied as is; otherwise precision truncates to that many codepoints, ? quotes and escapes, and width/fill/alignment pad (default left-aligned).

Notes

With ?, width and alignment are not applied (the quoted text is written unpadded).

`FmtBuf.put_bool`

inline fn put_bool(self, v: bool, spec: u64)

Appends true or false, padded per spec (default left-aligned).

`FmtBuf.put_char`

fn put_char(self, c: char, spec: u64)

Appends one character UTF-8 encoded, padded per spec; ? writes it quoted and escaped ('a').

`FmtBuf.put_byte`

fn put_byte(self, b: byte, spec: u64)

Appends a byte as two lowercase hex digits (ff); # adds 0x. A byte is storage, not a number, so there is no decimal form.

`FmtBuf.put_i8`

inline fn put_i8(self, v: i8, spec: u64)

Appends a i8 hole in decimal, or in the base the spec selects (x, o, b, with # for a prefix and + for a sign). Width, fill, alignment and 0 padding come from spec; numbers default to right-aligned.

`FmtBuf.put_i16`

inline fn put_i16(self, v: i16, spec: u64)

Appends a i16 hole in decimal, or in the base the spec selects (x, o, b, with # for a prefix and + for a sign). Width, fill, alignment and 0 padding come from spec; numbers default to right-aligned.

`FmtBuf.put_i32`

inline fn put_i32(self, v: i32, spec: u64)

Appends a i32 hole in decimal, or in the base the spec selects (x, o, b, with # for a prefix and + for a sign). Width, fill, alignment and 0 padding come from spec; numbers default to right-aligned.

`FmtBuf.put_i64`

inline fn put_i64(self, v: i64, spec: u64)

Appends a i64 hole in decimal, or in the base the spec selects (x, o, b, with # for a prefix and + for a sign). Width, fill, alignment and 0 padding come from spec; numbers default to right-aligned.

`FmtBuf.put_isize`

inline fn put_isize(self, v: isize, spec: u64)

Appends a isize hole in decimal, or in the base the spec selects (x, o, b, with # for a prefix and + for a sign). Width, fill, alignment and 0 padding come from spec; numbers default to right-aligned.

`FmtBuf.put_u8`

inline fn put_u8(self, v: u8, spec: u64)

Appends a u8 hole in decimal, or in the base the spec selects (x, o, b, with # for a prefix and + for a sign). Width, fill, alignment and 0 padding come from spec; numbers default to right-aligned.

`FmtBuf.put_u16`

inline fn put_u16(self, v: u16, spec: u64)

Appends a u16 hole in decimal, or in the base the spec selects (x, o, b, with # for a prefix and + for a sign). Width, fill, alignment and 0 padding come from spec; numbers default to right-aligned.

`FmtBuf.put_u32`

inline fn put_u32(self, v: u32, spec: u64)

Appends a u32 hole in decimal, or in the base the spec selects (x, o, b, with # for a prefix and + for a sign). Width, fill, alignment and 0 padding come from spec; numbers default to right-aligned.

`FmtBuf.put_u64`

inline fn put_u64(self, v: u64, spec: u64)

Appends a u64 hole in decimal, or in the base the spec selects (x, o, b, with # for a prefix and + for a sign). Width, fill, alignment and 0 padding come from spec; numbers default to right-aligned.

`FmtBuf.put_usize`

inline fn put_usize(self, v: usize, spec: u64)

Appends a usize hole in decimal, or in the base the spec selects (x, o, b, with # for a prefix and + for a sign). Width, fill, alignment and 0 padding come from spec; numbers default to right-aligned.

`FmtBuf.put_i128`

inline fn put_i128(self, v: i128, spec: u64)

Appends a i128 hole in decimal, or in the base the spec selects (x, o, b, with # for a prefix and + for a sign). Width, fill, alignment and 0 padding come from spec; numbers default to right-aligned.

`FmtBuf.put_u128`

inline fn put_u128(self, v: u128, spec: u64)

Appends a u128 hole in decimal, or in the base the spec selects (x, o, b, with # for a prefix and + for a sign). Width, fill, alignment and 0 padding come from spec; numbers default to right-aligned.

`FmtBuf.put_i256`

inline fn put_i256(self, v: i256, spec: u64)

Appends a i256 hole in decimal, or in the base the spec selects (x, o, b, with # for a prefix and + for a sign). Width, fill, alignment and 0 padding come from spec; numbers default to right-aligned.

`FmtBuf.put_u256`

inline fn put_u256(self, v: u256, spec: u64)

Appends a u256 hole in decimal, or in the base the spec selects (x, o, b, with # for a prefix and + for a sign). Width, fill, alignment and 0 padding come from spec; numbers default to right-aligned.

`FmtBuf.put_i512`

inline fn put_i512(self, v: i512, spec: u64)

Appends a i512 hole in decimal, or in the base the spec selects (x, o, b, with # for a prefix and + for a sign). Width, fill, alignment and 0 padding come from spec; numbers default to right-aligned.

`FmtBuf.put_u512`

inline fn put_u512(self, v: u512, spec: u64)

Appends a u512 hole in decimal, or in the base the spec selects (x, o, b, with # for a prefix and + for a sign). Width, fill, alignment and 0 padding come from spec; numbers default to right-aligned.

`FmtBuf.put_f16`

inline fn put_f16(self, v: f16, spec: u64)

Appends an f16 hole via the runtime formatter (rt/fmt.h), honouring the sign bit of -0.0 and NaN. Precision, width, fill and alignment come from spec; the e base selects exponent form, E with the upper flag.

`FmtBuf.put_bf16`

inline fn put_bf16(self, v: bf16, spec: u64)

Appends an bf16 hole via the runtime formatter (rt/fmt.h), honouring the sign bit of -0.0 and NaN. Precision, width, fill and alignment come from spec; the e base selects exponent form, E with the upper flag.

`FmtBuf.put_f32`

inline fn put_f32(self, v: f32, spec: u64)

Appends an f32 hole via the runtime formatter (rt/fmt.h), honouring the sign bit of -0.0 and NaN. Precision, width, fill and alignment come from spec; the e base selects exponent form, E with the upper flag. With spec == 0 it writes the shortest round-trip digits in place.

`FmtBuf.put_f64`

inline fn put_f64(self, v: f64, spec: u64)

Appends an f64 hole via the runtime formatter (rt/fmt.h), honouring the sign bit of -0.0 and NaN. Precision, width, fill and alignment come from spec; the e base selects exponent form, E with the upper flag. With spec == 0 it writes the shortest round-trip digits in place.

`FmtBuf.put_f128`

inline fn put_f128(self, v: f128, spec: u64)

Appends an f128 hole via the runtime formatter (rt/fmt.h), honouring the sign bit of -0.0 and NaN. Precision, width, fill and alignment come from spec; the e base selects exponent form, E with the upper flag.

`FmtBuf.put_ptr`

fn put_ptr(self, addr: usize, name: *const u8, name_len: usize, spec: u64)

Appends a pointer hole as <name> @ 0x<hex>, or &null for address 0.

Parameters

addr: the pointer's address.
name: the pointee's spelling, a constant at the call site.
name_len: byte length of name.

Notes

spec is currently ignored.

`FmtBuf.finish`

inline fn finish(self) -> string

Hands the buffer over as an owned string, NUL-terminated, and empties this FmtBuf.

A spilled buffer's heap block is passed on as is; an inline one is copied to a new allocation of exactly len + 1 bytes. Afterwards data is null and the buffer may be written again.

`FmtBuf.view`

inline fn view(self) -> string

Returns the text so far as a borrowed string (capacity 0), without copying.

Valid until this FmtBuf is written again, cleared or destroyed.

Notes

Calling it after finish(), before anything is written again, writes through a null data and crashes.

`FmtBuf.clear`

inline fn clear(self)

Empties the buffer, keeping its storage (inline or heap) for reuse.

Generated from Kairo source, Apache-2.0 WITH AdditionRef-Kairo-Runtime-exception.