Standard Library Reference

std.strings

String utilities beyond the built-ins. Pure and RT-safe. String offsets and length are byte-based, matching substring and indexOf.

import std.strings.*;

"7" padStart(3, "0")                -- "007"
"a\r\nb\nc\n" splitLines             -- [a, b, c]
"snare_04.wav" glob("snare_*.wav")  -- true
"beat7" glob("beat[0-9]")           -- true

std.path

Pure path-string manipulation — no syscalls, RT-safe. Paths are byte strings with / separators. The filesystem itself lives in std.fs.

import std.path.*;

"/a/b/c.txt" basename               -- "c.txt"
"/a/b/c.txt" dirname                -- "/a/b"
"take1.wav" withExtension(".aif")   -- "take1.aif"
joinPath("samples", "kick.wav")     -- "samples/kick.wav"

std.fs NRT

Ergonomic wrappers over the NRT file built-ins (readFile, writeFile, listDir, …). Nothing here is real-time safe: the plain wrappers block on syscalls, and the Async wrappers — non-blocking, built on the readFileAsync-family built-ins — are still rejected in real-time code. The Result variants carry a path-bearing error message via std.result.

import std.fs.*;

readLines("setlist.txt") unwrapOr(["(empty)"]) println;
writeLines("/tmp/out.txt", ["one", "two"]);
readFileResult("missing") errOption unwrap println;
                        -- cannot read file: missing

std.result

Result<T, E> is a success-or-error sum type. Convention: built-ins that can fail return Option; stdlib .x APIs that want an error message return Result<T, String>.

import std.result.*;

fn half(x Int) Result<Int, String> {
    x % 2 == 0 ? Result<Int, String>.ok(x / 2)
               : Result<Int, String>.err("odd: " $ x toString)
}

half(8) unwrapOr(0) println;                 -- 4
half(7) errOption unwrap println;            -- odd: 7

The postfix try operator propagates errors without boilerplate: expr try unwraps ok/some, and on err/none early-returns it from the enclosing function (whose return type must be a Result with the same error type, or an Option). It chains mid-pipeline like await.

fn quarter(x Int) Result<Int, String> {
    let h = half(x) try;         -- err propagates out of quarter
    let q = half(h) try;
    Result<Int, String>.ok(q)
}

quarter(8) unwrapOr(0) println;              -- 2
quarter(6) errOption unwrap println;         -- odd: 3

std.test

Assertion helpers with stable one-line output (PASS label / FAIL label: expected X got Y), designed to compose with the golden-file test runner and read well in the app's output panel. Each assertion returns its outcome as a Bool and updates shared counters.

import std.test.*;

assertEq(2 + 2, 4, "ints add");       -- PASS ints add
assertNear(0.1 + 0.2, 0.3, 1e-9, "float near");
let failures = testSummary();          -- 2 passed, 0 failed

std.thunk

Memoized lazy values: a Thunk<T> wraps a deferred computation that runs at most once; force evaluates it on first use and caches the result in place.

import std.thunk.*;

let t = thunk(fn() Int { expensive() });
t force println;    -- computed now
t force println;    -- cached

std.futures

Combinators over Future<T> from the async/await core.

std.json

The Json value enum (null, bool, number, string, array, object) and toString rendering. A parser returning Result<Json, String> is planned (see the roadmap in devplans/LANG_IMPLEMENTATION_PLAN.md). For fast binary interchange, prefer std.message's TZB codec.

std.message / std.messageEncoding

Msg is the dynamic message value type (bool/int/float/symbol/string/vec) with asMsg constructors; std.messageEncoding provides the TZB binary codec: encode(Msg) → Bytes, decode(Bytes) → Msg, isMessage, and a zero-copy Reader with O(1) child access for columnar vectors. Used by the actor system and the NATS bridge. The TZB format itself — the wire layout and the matching C++ API — is documented in FFI Guide §15, Binary Messages.

std.notebook NRT

Builds the app's .tzd notebook documents (Live Controls & Notebooks) programmatically — a .tzd file is a TZB-encoded Msg tree, so this module assembles the document records and hands them to std.messageEncoding. Cells are described with NotebookCell values, normally via the constructors below. Generated documents contain no widget records — give the notebook a run-on-load code cell and its ui constructors recreate the widgets on open — and no undo history, so the file opens with a fresh history tree.

import std.notebook.*;

saveNotebook("demo.tzd", [
    proseCell("# Sine demo"),
    panelCell("main"),
    codeCell("import ui.*;\npanel(\"main\");\nslider(\"freq\", 20.0, 2000.0, 440.0);", true),
]);