Fmt

This library is in flux. APIs may change without notice. Generated from source with koruc 0.1.7 on 11/4/2026.

import std/fmt

Koru Standard Library: String Formatting

fmt.kz · 5 tors · ~[comptime]· ~[runtime]

Koru Standard Library: String Formatting Zero-overhead string formatting with Liquid-style templates. Returns allocated strings with phantom obligation tracking. DESIGN: "Hidden but overridable" - fmt.blk: Uses page_allocator internally, user never thinks about it - fmt.blk.with_allocator: Explicit control when needed - Auto-discharge handles cleanup via phantom obligations

Phantom lifecycles

Derived from the phantom labels in the declarations below — state! issues an obligation the compiler will chase, !state discharges it, a bare state holds it without moving it. Nothing here is hand-drawn.

FormattedText 1 state

string 2 states allocated!

fmt.dealloc

<!allocated> koru_std/fmt.kz:32

// FMT.DEALLOC - Discharge the <allocated!> obligation
~pub tor fmt.dealloc { formatted: *FormattedText<!allocated> }

fmt.blk

comptimetransform koru_std/fmt.kz:61

// The transform tor returns SiteResult (the rewritten site) — the single-return
// form every `[transform]` decl lands as (frag-single-return-form-is-universal;
// `ln` is the twin). The RUNTIME value is the allocated string; a caller binds
// it with `: name` (`f` above). An unbound site refuses at the transform —
// the `| formatted` branch spelling was removed, leaving the result no
// consumer (KORU180, 620_020). The `<allocated!>` obligation rides that
// runtime value, not the transform tor's own return.
~[comptime|transform] pub tor fmt.blk {
    source: Source,
    invocation: *const Invocation,
    item: std/compiler:*const Item,
    program: std/compiler:*const Program,
    reporter: std/compiler:*ErrorReporter,
    allocator: std.mem.Allocator
} -> SiteResult

fmt.blk.impl

norun <std.io:allocated!> koru_std/fmt.kz:70

~[norun] pub tor fmt.blk.impl { text: string } -> string<std.io:allocated!>

ln

comptimetransform koru_std/fmt.kz:383

// TODO: fmt.blk.with_allocator - requires solving how user params
// coexist with transform infrastructure params in the pass runner.
// [comptime|transform]pub tor fmt.blk.with_allocator { ... }
//
// FMT.LN - One-line format with Liquid templates, returns text via continuation
//
// Syntax:
//   std/fmt:ln("Hello {{ name:s }}! Count: {{ count:d }}")
//   : l |> ... use l.text ...
//
// Zero allocation: `.text` BORROWS the site's threadlocal scratch —
// valid only until THIS call site runs again. `l` carries scratch@scoped:
// read `.text` freely in frame, never produce it out (`-> l.text` refuses).
// The scratch is per-call-site: `[size(16k)]` on the call sizes THIS
// site's buffer (digits + optional k/m; absent: 4096). A bad size is a
// compile error; overflow panics naming the site's size.
// Escape = copy (std/string:from-page + take) or own (fmt.blk). 620_011.
// The {{ var:spec }} placeholders are resolved at compile time into
// std.fmt.bufPrint calls that run at runtime in the caller's scope.
~[comptime|transform] pub tor ln {
    invocation: *const Invocation,
    item: std/compiler:*const Item,
    program: std/compiler:*const Program,
    reporter: std/compiler:*ErrorReporter,
    allocator: std.mem.Allocator
} -> SiteResult

ln.impl

norun <scratch@scoped> koru_std/fmt.kz:391

~[norun] pub tor ln.impl { expr: string } -> string<scratch@scoped>

~part jsprec `koru_std/fmt.jsprec.kz`

Koru Standard Library: String Formatting — JS placeholder emission. Joined via `~part jsprec` in fmt.kz; merged into the fmt module at load. Emit one `{{ ... }}` placeholder's value expression for the JS concat the `ln|js` transform is building — bare `name` normally, `Number(name).toFixed(N)` when the spec carries a `:.N` precision tail (`d:.4`, `f:.2`, `:.4`). JS `+` already stringifies every other spec, so they still collapse to the bare name — `s`/`S`/`d`/`f`/`any` unchanged. A dotted path (`req.text`) is a JS member read verbatim, and a segment that collides with a JS keyword is still a legal property name — so unlike |zig there is nothing to escape here.

~part csprec `koru_std/fmt.csprec.kz`

Koru Standard Library: String Formatting — CS placeholder emission. Joined via `~part csprec` in fmt.kz; merged into the fmt module at load. One `{{ ... }}` placeholder as an interpolation HOLE inside a `$"…"` literal — `fmt.blk|cs`/`ln|cs` emit the interpolated-string form because the C# compiler lowers it to DefaultInterpolatedStringHandler: one pooled buffer, one allocation for the result, no substring per placeholder. A `+` concat with `__koru_str(…)` calls pays a ToString substring per placeholder — measurable on a hot loop (012_threat_scanner: ~300ms on 6M elements). Numeric specs (`:d`, `:f`) get a bare `{expr}` hole: the operand is a numeric contract and AppendFormatted<T> writes digits straight into the buffer — no substring, no helper call. Everything else keeps `__koru_str` inside the hole (bool unwrapping, `:S` payload); for a string operand the helper returns the same reference, so the common `{{ s:s }}` is still zero-alloc. Precision keeps its InvariantCulture ToString inside the hole — the `:.N` tail renders `expr.ToString("F"+N, InvariantCulture)` so a French locale doesn't answer "3,14" for "3.14". A dotted path (`req.text`) is a cs member read verbatim, and a segment that collides with a C# keyword is legal after a dot — nothing to escape.

~part lnzig `koru_std/fmt.lnzig.kz`

Koru Standard Library: String Formatting — ln zig-target transform. Joined via `~part lnzig` in fmt.kz; merged into the fmt module at load. The [size(N)] scratch sizing is parsed here — see the transform body.