vera:format

String formatting and buffer building. Every function takes (buf, offset, buf_size, ...) and returns the new offset. Bounds-checked — writes are clamped to buf_size.

import "vera:format"

Overview

vera:format provides an append-based string formatting API. Each fmt_* function writes formatted data into a buffer starting at the given offset and returns the updated offset. This pattern allows chaining calls to build complex strings incrementally.

The module is pure VERA — it uses zero compiler primitives and is built entirely on vera:string and vera:memory.

Dependencies

vera:string — for int_to_string
vera:memory — for copy_memory

Functions

fmt_str

Append raw bytes to the buffer.

function fmt_str(buf: ptr, offset: i64, buf_size: i64, str: ptr, len: i64) -> i64

Parameter	Type	Description
`buf`	`ptr`	Destination buffer
`offset`	`i64`	Current write position
`buf_size`	`i64`	Total buffer capacity
`str`	`ptr`	Source bytes to append
`len`	`i64`	Number of bytes to append

Returns: New offset after the appended bytes. If appending would exceed buf_size, only the bytes that fit are written.

fmt_int

Append a signed i64 as decimal text.

function fmt_int(buf: ptr, offset: i64, buf_size: i64, value: i64) -> i64

Parameter	Type	Description
`buf`	`ptr`	Destination buffer
`offset`	`i64`	Current write position
`buf_size`	`i64`	Total buffer capacity
`value`	`i64`	Signed integer to format

Returns: New offset. Examples: 42 → "42", -7 → "-7", 0 → "0".

fmt_uint

Append an unsigned i64 as decimal text.

function fmt_uint(buf: ptr, offset: i64, buf_size: i64, value: i64) -> i64

Parameter	Type	Description
`buf`	`ptr`	Destination buffer
`offset`	`i64`	Current write position
`buf_size`	`i64`	Total buffer capacity
`value`	`i64`	Unsigned integer to format

Returns: New offset. Treats the value as unsigned — no sign prefix.

fmt_hex

Append an i64 as lowercase hexadecimal (no 0x prefix).

function fmt_hex(buf: ptr, offset: i64, buf_size: i64, value: i64) -> i64

Parameter	Type	Description
`buf`	`ptr`	Destination buffer
`offset`	`i64`	Current write position
`buf_size`	`i64`	Total buffer capacity
`value`	`i64`	Value to format as hex

Returns: New offset. Examples: 255 → "ff", 57005 → "dead", 0 → "0".

fmt_char

Append a single byte.

function fmt_char(buf: ptr, offset: i64, buf_size: i64, byte: i8) -> i64

Parameter	Type	Description
`buf`	`ptr`	Destination buffer
`offset`	`i64`	Current write position
`buf_size`	`i64`	Total buffer capacity
`byte`	`i8`	Byte value to append

Returns: New offset (offset + 1), or offset if the buffer is full.

fmt_bool

Append "true" or "false".

function fmt_bool(buf: ptr, offset: i64, buf_size: i64, value: i32) -> i64

Parameter	Type	Description
`buf`	`ptr`	Destination buffer
`offset`	`i64`	Current write position
`buf_size`	`i64`	Total buffer capacity
`value`	`i32`	Boolean value (0 = false, non-zero = true)

Returns: New offset after appending "true" (4 bytes) or "false" (5 bytes).

fmt_float

Append an f64 as decimal with 6 fractional digits.

function fmt_float(buf: ptr, offset: i64, buf_size: i64, value: f64) -> i64

Parameter	Type	Description
`buf`	`ptr`	Destination buffer
`offset`	`i64`	Current write position
`buf_size`	`i64`	Total buffer capacity
`value`	`f64`	Floating-point value to format

Returns: New offset. Format: [-]integer.fraction with exactly 6 fractional digits. Examples: 3.14159265 → "3.141592", -0.5 → "-0.500000", 0.0 → "0.000000".

fmt_pad_left

Right-align: prepend fill bytes to reach width, then append str.

function fmt_pad_left(buf: ptr, offset: i64, buf_size: i64, str: ptr, len: i64, width: i64, fill: i8) -> i64

Parameter	Type	Description
`buf`	`ptr`	Destination buffer
`offset`	`i64`	Current write position
`buf_size`	`i64`	Total buffer capacity
`str`	`ptr`	String to right-align
`len`	`i64`	Length of string
`width`	`i64`	Minimum field width
`fill`	`i8`	Fill byte (e.g., `' '` or `'0'`)

Returns: New offset. If len >= width, appends str with no padding.

fmt_pad_right

Left-align: append str, then fill bytes to reach width.

function fmt_pad_right(buf: ptr, offset: i64, buf_size: i64, str: ptr, len: i64, width: i64, fill: i8) -> i64

Parameter	Type	Description
`buf`	`ptr`	Destination buffer
`offset`	`i64`	Current write position
`buf_size`	`i64`	Total buffer capacity
`str`	`ptr`	String to left-align
`len`	`i64`	Length of string
`width`	`i64`	Minimum field width
`fill`	`i8`	Fill byte (e.g., `' '` or `'0'`)

Returns: New offset. If len >= width, appends str with no padding.

Usage Pattern

import "vera:format"
import "vera:memory"
import "vera:io"

function main() -> i32 {
    ; Allocate a 256-byte buffer
    call buf, allocate, 256
    constant.i64 buf_size, 256
    constant.i64 zero, 0

    ; Build a formatted string
    copy.i64 off, zero
    constant.ptr hello, _greeting
    constant.i64 hello_len, 7
    call off, fmt_str, buf, off, buf_size, hello, hello_len

    constant.i64 value, 42
    call off, fmt_int, buf, off, buf_size, value

    constant.i8 newline, 10
    call off, fmt_char, buf, off, buf_size, newline

    ; Write the result
    call _, write_stdout, buf, off

    ; Clean up
    call _, free, buf, buf_size

    constant.i32 exit_code, 0
    return exit_code
}

data _greeting: "Hello, "

The VERA Book