Module: libc.format

Source: ./libc/format.reef

Overview

libc.format - Number formatting into caller buffers (compatibility façade)

Thin wrappers over core.convert + core.str. The historical C sprintf FFI (c_sprintf_*) was never shipped in the runtime; this module reimplements the exported names in pure Reef so import libc.format links.

This module FORMATS only. Its parse_* family (-1 on invalid input) was deleted by 0.9.2 C12: parsing lives in core.convert (from_hex, from_octal, from_binary, returning Result), which is the one place it belongs and which already carried the overflow guards these lacked.

Prefer core.convert directly for new code (allocating APIs that return string / Result). These sprintf_* helpers keep the old buffer-filling signatures for call-site compatibility.

Buffer contract for sprintf_*:

• buffer must be a heap-allocated mutable string (e.g. reef_alloc_string_buffer / reef_string_alloc), not a string literal.
• Destination capacity is the heap-block length (bytes), which includes one byte for the trailing NUL. Max chars written = capacity - 1.
• If the formatted text is longer than that, the write is truncated to fit (no OOB). Typical maxima for a 32-bit int: hex ≤ 8 digits, octal ≤ 11, prefixed hex ≤ 10, padded forms ≤ max(width, digits) — allocate generously (e.g. 64) when unsure if you need the full form.
• Returns the number of characters actually written (not counting NUL), which may be less than the untruncated formatted length when clamped.

Functions

fn write_into(buffer: string, formatted: string): int

Overwrites buffer with formatted and publishes str_len. Clamps to destination capacity (heap-block length minus one for NUL) so undersized buffers never OOB before set_length. Capacity is the block length field — not logical str_len — so a prior shorter write does not shrink the usable destination. Returns chars actually written.

fn sprintf_hex(buffer: string, value: int): int

Formats integer as uppercase hexadecimal (e.g., "FF")

fn sprintf_hex_lower(buffer: string, value: int): int

Formats integer as lowercase hexadecimal (e.g., "ff")

fn sprintf_hex_prefixed(buffer: string, value: int): int

Formats integer as prefixed hexadecimal (e.g., "0xFF")

fn sprintf_octal(buffer: string, value: int): int

Formats integer as octal (e.g., "377")

fn sprintf_padded(buffer: string, value: int, width: int): int

Formats integer as zero-padded decimal (e.g., "0042" with width 4) Note: convert uses zero-padding (same as the old %0Nd C path).

fn sprintf_hex_padded(buffer: string, value: int, width: int): int

Formats integer as zero-padded uppercase hex (e.g., "00FF" with width 4)

Generated by reefc doc