The standard library

Modules written in Nexium and embedded in the compiler. import std.<module> makes it available as <module>.function(...); nothing to install or link. The core containers (List, String, Map), formatting, and the math, io, os, time, random, mem, and process namespaces are compiler builtins and are documented in language.md.

Sources are in std/; each module carries its own test blocks, run by nx test std/<module>.nx and by the test harness. This file is generated by scripts/std_docs.py from the doc comments.

std.args#

std.args: command-line argument parsing, written in Nexium. import std.args then: var p = args.Parser.new(os.args()) let verbose = p.flag("--verbose", "-v") let level = p.option("--level", "-l") orelse "info" let files = p.rest() Long options take --name value or --name=value; short ones -n value. Everything after -- is positional. Unknown options stay in rest() so the caller can report them.

Types: Parser

std.base64#

std.base64: base64 (RFC 4648), written in Nexium: the standard alphabet with its = padding, and the URL-safe one (- and _ for + and /) without, as JSON Web Tokens and URLs carry it. import std.base64 then: let s = base64.encode("hi!") // "aGkh" let raw = try base64.decode(s) let token = base64.encode_url(key) // no =, safe in a URL let back = try base64.decode_url(token) Decoding is strict: a character outside the alphabet, padding anywhere but at the end or more of it than the length needs, or a length no encoding produces is error.InvalidInput. std.bytes keeps the lenient reader, unbase64, which skips line breaks and stray padding.

std.bytes#

std.bytes: encodings and byte-level utilities, written in Nexium. import std.bytes then bytes.hex(data), bytes.base64(data), ... Decoders return error.InvalidInput on malformed text.

std.csv#

std.csv: comma-separated values (RFC 4180), written in Nexium: reading rows, reading rows by their header, and writing rows. import std.csv then: let rows = try csv.parse(text) // List(List(String)) for row in try csv.by_header(text) { // Map(String, String) let name = row["name"] orelse "?" } let tsv = try csv.parse_with(text, '\t') let out = csv.to_text(&rows) // quoted where needed, CRLF A field in double quotes may hold the separator, line breaks and "" for a quote. A quote inside an unquoted field, anything but the separator or a line end after a closing quote, and a quoted field never closed are error.InvalidInput. Lines may end in CRLF or LF, empty lines are skipped, and a leading UTF-8 byte-order mark is dropped.

std.deque#

std.deque: a double-ended queue, written in Nexium: two Lists back to back, the first kept reversed, so both ends push and pop in O(1) amortized (when one side runs out, half of the other moves over). import std.deque then: var q = deque.of(Job) q.push_back(job) q.push_front(urgent) let next = q.pop_front() orelse return if let last = q.last() { ... } // a view, left in place

Types: Deque(T){

std.env#

std.env: the environment, and where a program keeps its files, written in Nexium: variables, the home directory, the config, data, cache and state directories each platform expects (XDG on Linux and the BSDs, Library on macOS, AppData on Windows), and .env files. import std.env then: let port = env.get_or("PORT", "8080") let dir = env.config_dir("myapp") // ?String: ~/.config/myapp, ... let notes = env.expand_home("~/notes.txt") let n = env.load_dotenv(".env", false) catch 0 // sets what is not set yet The directories are where a program should keep its files; nothing here creates them (fs.make_dirs does). Each is null when the variables it comes from are not set.

Types: Var

std.fs#

std.fs: files, directories and paths, written in Nexium. import std.fs then: if fs.exists("notes.txt") { ... } try fs.make_dirs("out/logs") for name in try fs.list("out") { ... } for path in try fs.walk("src") { ... } // every file, recursively let cfg = fs.join(fs.parent(argv0), "app.toml") The platform calls are the io.* builtins (documented in the language reference); this module adds sorted listings, recursive create and remove, and a walker. Its path functions call std.path's, which has more. Paths are byte strings; / and \ both separate components on every platform, and results use / unless the input used \.

std.hash#

std.hash: hash functions, written in Nexium: FNV-1a (64-bit), SipHash-2-4 (keyed: a table whose keys an adversary picks), SHA-256 (checksums and content addresses), and SHA-1 for the protocols that still require it. import std.hash then: let h = hash.fnv1a64(name) // fast, not keyed let k = hash.siphash(key16, name) // keyed with 16 bytes let sum = hash.sha256_hex(file_text) // 64 hex digits var s = hash.Sha256.new() // or piece by piece s.update(part1) s.update(part2) let digest = s.finish() // 32 bytes std.bytes keeps the 32-bit fnv1a and crc32.

Types: Sha256

std.heap#

std.heap: a priority queue, written in Nexium: a binary heap over a List, ordered by a comparison of your own. import std.heap then: var q = heap.by(Job, |a: *Job, b: *Job| -> bool { return a.due < b.due }) q.push(job) while true { let next = q.pop() orelse break // the least by the comparison first run(next) } push and pop are O(log n), peek O(1). A heap that pops the greatest first is one whose comparison says a > b.

Types: Heap(T){

std.http#

std.http: an HTTP/1.1 client and a small server, written in Nexium over std.net and std.stream. import std.http then: let r = try http.get("https://example.com/") // TLS by the system's own library println("{} {}", .{r.status, r.body.len}) if let ct = r.header("content-type") { ... } var client = http.client_with(NxTls, &mut layer) // or a TLS layer of a package's client.timeout_ms = 10000 // and timeouts, redirects, limits var s = try client.open("GET", "https://example.com/big", &headers, "") while true { // the body as it arrives let piece = (try s.next()) orelse break ... } s.close() fn hello(req: *http.Request) -> http.Response { return http.text(200, "hello from Nexium") } var router = http.Router.new() router.get("/", hello) var server = try http.Server.bind("127.0.0.1", 8080) try server.serve(&router) // forever, one request at a time The client speaks HTTP/1.1 with Connection: close over a Transport: TCP for http://, and for https:// the TLS layer a program hands its client (the slot of decision 120, which nxtls, the TLS 1.3 client written in Nexium, fills), or without one SystemTls, the platform's own: SChannel on Windows, Security.framework on macOS, OpenSSL on Linux and the BSDs, each checking the server's certificate against the system's roots and the host's name (SystemTls.problem() says why one failed). It reads a body by Content-Length, chunked encoding, or until the connection ends (refused when a TLS connection was cut rather than closed, as nothing then shows the body is whole), whole or as it arrives, follows up to five redirects, and gives up on a connect or a wait after timeout_ms. The server handles one connection at a time, which is what a tool, a local dashboard or a test needs; threads come later in the roadmap.

Types: Header, Url, Response, Plain, SystemTls, Streaming(T){, Client(T){, Request, Route, Router, Server

std.json#

std.json: a JSON parser and serializer, written in Nexium. import std.json then json.parse(text), json.stringify(&value). Values are the Json enum below; arrays and objects own their children. Numbers are f64 (JSON has one number type); integers up to 2^53 round trip.

Types: Member, Json

std.lists#

std.lists: generic helpers over slices and Lists, written in Nexium. import std.lists then lists.sum(xs), lists.map(f, xs), ... Functions take slices, so arrays, Lists, and slices all work; results that are new collections are returned as owned Lists.

std.log#

std.log: leveled, structured logging, written in Nexium: a message and named fields, as a line of text a person reads or a line of JSON a machine reads, on stderr. import std.log then: var l = log.Logger.new(log.Level.Info) l.info("listening", [log.int("port", 8080), log.str("host", host)][..]) l.warn("slow answer", [log.float("seconds", 2.5)][..]) l.debug("not shown: below the logger's level", []) var j = log.Logger.json(log.Level.Debug) // one JSON object a line let level = log.parse_level(env.get_or("LOG", "info")) orelse log.Level.Info var request = l.with([log.str("id", id)][..]) // every line carries the id A text line is 2026-09-25T18:04:05.120Z INFO listening port=8080 host=0.0.0.0, a value with a space, = or a quote in quotes; a JSON line is {"time":"2026-09-25T18:04:05.120Z","level":"info","msg":"listening", "port":8080,"host":"0.0.0.0"}.

Types: Level, Field, Logger

std.net#

std.net: TCP and UDP with addresses, written in Nexium over the net.* primitives. import std.net then: var c = try net.TcpStream.connect("example.com", 80) try c.send("GET / HTTP/1.0\r\nHost: example.com\r\n\r\n") let reply = try c.recv_all() // until the peer closes c.close() var l = try net.TcpListener.bind("127.0.0.1", 8080) while true { var conn = try l.accept() var r = conn.reader() // a std.stream Reader let line = try r.read_line() try conn.send("ok\n") conn.close() } var u = try net.UdpSocket.bind("0.0.0.0", 0) try u.send_to("127.0.0.1", 9000, "ping") let d = try u.recv_from(1500) // d.data, d.from Every call blocks; timeouts are per socket (set_timeout, milliseconds, 0 waits forever) and expire with error.Timeout. recv returns an empty String when the peer has closed. Errors: NotFound (name lookup), ConnectionRefused, Timeout, IoError.

Types: Addr, TcpStream, TcpListener, Datagram, UdpSocket

std.num#

std.num: integer utilities, written in Nexium. import std.num then num.gcd(12, 18), num.clamp(x, 0, 10), ... The math namespace (sqrt, sin, pow on floats, ...) is a compiler builtin; this module covers what is naturally integer work.

std.path#

std.path: paths as text, written in Nexium: joining, splitting, comparing and normalizing them, without touching the file system (std.fs does that). import std.path then: let cfg = path.join(path.parent(argv0), "app.toml") let ext = path.extension("notes.tar.gz") // "gz" let n = path.normalize("a/./b/../c") // "a/c" let r = path.relative("src/app", "src/lib/x.nx") // "../lib/x.nx" for part in path.components("/usr/local/bin") { } // "/", "usr", "local", "bin" Paths are byte strings. / and \ both separate components on every platform, and a result uses / unless its input used \. A path is absolute when it starts at a root: /, \, a drive (C:\, C:/) or a share (\\server). std.fs keeps its path functions, which call these.

std.process#

std.process: run programs and capture what they print, or talk to them while they run, written in Nexium over the process.* primitives. import std.process then: let out = try process.run(["git", "status", "--short"]) if out.ok() { print("{}", .{out.stdout}) } let r = try process.run_with(["sort"], process.Options{ .stdin = "b\na\n", .cwd = "" }) let sh = try process.shell("echo hi") // cmd /C on Windows, sh -c elsewhere The child inherits the environment. error.IoError when the program cannot be started; a non-zero exit is reported in code, not as an error. The input is written as the child takes it while its output is read as it comes, so a program that writes before it reads its input, however much, finishes as it would in a terminal. A program can also run alongside, talked to while it runs: var py = try process.start(["python", "-i", "-q"]) try py.stdin.write_line("print(6 * 7)") let answer = try py.stdout.read_line() // "42" let status = try py.wait() // closes its input first var build = try process.start_with(["make"], process.Start{ .stderr = process.Stdio.Merge }) while true { let line = (try build.stdout.read_line()) orelse break println("{}", .{line}) } Output a program writes while this one waits for something else (its input to go in, the other stream, its end) is kept until read, so it never stalls on a full pipe. set_timeout bounds every wait (error.Timeout); kill and terminate end it early. Exit codes and signals have names (EXIT_USAGE, SIGTERM, exit_name, signal_name), and trap_signals lets this program catch Ctrl-C and SIGTERM to finish cleanly (caught, wait_signal).

Types: Output, Options, Status, Stdio, Start, PipeReader, PipeWriter, Child

std.regex#

std.regex: regular expressions without backtracking, written in Nexium. import std.regex then: let re = try regex.compile("(\\w+)@(\\w+)\\.com") if re.is_match(text) { ... } if let m = re.find(text) { println("{} at {}", .{m.text(), m.start}) } for m in re.find_all(text) { println("{}", .{m.group(1).?}) } let out = re.replace_all(text, "$2:$1") let parts = try regex.compile(",\\s") for p in parts.split("a, b,c") { ... } Syntax: literals, . (any byte but newline), classes [a-z] [^...], \d \w \s \D \W \S \b \B, escapes \. \\ \n \t \r, anchors ^ $, groups (...) and (?:...), alternation |, repeats ` + ? {n} {n,} {n,m}and their lazy forms*? +? ??`. Matching is a Pike VM (Thompson's NFA simulation), so every search is linear in the text and the pattern; there are no back-references. Patterns and text are bytes.

Types: Regex, Match

std.set#

std.set: a set of values, written in Nexium over Map(T, bool): its elements are the types a Map takes as keys (integers, bool, char, []u8, String). import std.set then: var seen = set.of(i64) if seen.add(id) { println("new: {}", .{id}) } let common = set.intersection(i64, &a, &b) add, contains and remove take a value like a Map's key: a copy, or for a String set an owned string (name.clone() keeps yours).

Types: Set(T){

std.sort#

std.sort: sorting by a comparison of your own, stable sorting, and searching sorted slices, written in Nexium over the slice's swap. import std.sort then: sort.by(Point, points[..], |a: *Point, b: *Point| -> bool { return a.x < b.x }) sort.stable_by(Task, tasks[..], by_priority) // equal elements keep their order sort.by_key(Point, i64, points[..], |p: *Point| -> i64 { return p.y }) let at = sort.binary_search(i64, xs[..], 42) // a position of 42, or null by is a heapsort: in place, O(n log n) comparisons whatever the input, and not stable. The stable sorts merge-sort the positions and then move each element into place along the cycles of the permutation, so no element is ever copied and any element type sorts. xs.sort() sorts by < without a comparison.

std.stream#

std.stream: buffered readers and writers over files and the standard streams, written in Nexium. import std.stream then: var r = try stream.Reader.open("big.log") while true { // no whole-file allocation let line = (try r.read_line()) orelse break ... } r.close() var w = try stream.Writer.open("out.txt") try w.write_line("hello") try w.close() // flushes, then closes var input = stream.Reader.stdin() var out = stream.Writer.stdout() try stream.copy(&mut input, &mut out) try out.flush() Readers buffer 64 KB at a time; writers gather output and flush when the buffer fills, on flush, and on close. A Writer must be flushed or closed before the program ends, or buffered output is lost.

Types: Reader, Writer

std.strings#

std.strings: text utilities on []u8 and String, written in Nexium. import std.strings then strings.join(parts, ", "). The core methods (len, split, trim, find, starts_with, parse_int, ...) are compiler builtins; this module adds what is naturally written in the language itself. Slices returned here point into the argument they were cut from; String results are owned by the caller.

std.testing#

std.testing: conveniences for test blocks, written in Nexium. import std.testing then, inside a test: testing.expect_approx(area, 3.14159, 0.001) testing.expect_err(i32, parse("nope")) testing.expect_contains(output, "42 items") testing.expect_lines(rendered, expected) // reports the first differing line testing.expect_snapshot("report", rendered) // compares to snapshots/report.txt try testing.snapshot("report", rendered) // the same, as an error union fn lists(r: *mut testing.Rng) -> List(i64) { ... r.size(20) ... r.int(-50, 50) ... } testing.check(List(i64), lists, |xs: *List(i64)| -> bool { ... }) // a property Snapshots live in snapshots/<name>.txt under the current directory. A missing file is written and the test passes; a mismatch fails with the first differing line and how to accept the new output. Set NX_UPDATE_SNAPSHOTS=1 to rewrite them all. A property is checked on 100 random values (NX_CASES for more, NX_SEED for another seed). Generators draw from a Rng, which keeps every choice, so a failing case is shrunk by making it again from fewer and lower choices while it still fails: the report is about the smallest case found, with no shrinking code of the generator's own. search is the driver without the panic; the compiler's fuzzer runs on it.

Types: Rng, Search, Failure

std.text#

std.text: UTF-8 text by code point and by grapheme cluster, written in Nexium, with the Unicode tables it needs. import std.text then: let n = text.char_count("héllo") // 5 code points, not 6 bytes for c in text.scalars("héllo") { ... } // chars (Unicode scalars) let g = text.grapheme_count("🇯🇵 e\u{301}") // 3: a flag, a space, an é for g in text.graphemes(s) { ... } // what a reader counts as characters let w = text.width("日本語") // 6 columns on a terminal let cell = text.pad_right(text.truncate_width(name, 20), 20) let s = text.to_upper("straße") // "STRASSE" let same = text.eq_ignore_case("Straße", "STRASSE") let t = text.truncate("héllo wörld", 5) // "héllo", never mid-character Strings are bytes; this module reads them as UTF-8, tolerating bad input (an invalid byte decodes as U+FFFD and advances one byte). Grapheme clusters are Unicode's extended grapheme clusters (UAX #29): a letter and its marks, a Hangul syllable, an emoji sequence joined by ZWJ, a flag, an Indic conjunct. Case mapping is Unicode's full mapping for every script, without the rules that depend on a language (Turkish and Lithuanian i); to_lower writes a final sigma where a word ends. width counts terminal columns as terminals draw them: East Asian wide and fullwidth characters and emoji sequences take two, marks and zero-width characters none. The tables at the end are generated by scripts/unicode_tables.py (UNICODE_VERSION says from which version).

Types: Decoded

std.thread#

std.thread: threads, channels, select, mutexes and atomics, written in Nexium over the thread.* and sync.* primitives. import std.thread then: fn work(job: *mut Job) -> i64 { ... } var t = thread.spawn(Job, i64, work, Job{ .from = 0, .to = 1000 }) let total = t.join() // the function's result fn produce(p: *mut Producer) { ... } // no result: a Worker var ch = thread.channel(String) // shared by pointer var producer = thread.run(Producer, produce, Producer{ .out = &mut ch }) let msg = ch.recv() orelse break // null once closed and drained producer.join() var counter = thread.mutex(i64, 0) let n = counter.lock() // mut i64 while held n. += 1 counter.unlock() var hits = thread.atomic(0) // an i64 changed without a lock _ = hits.add(1) // two channels at once: which has a value (or closed), null after 1 s let which = thread.select2(Job, bool, &mut jobs, &mut quit, 1000) orelse continue // threads that end before the call does, so they may point into locals thread.each(Stage, stages[..], run_stage) // a thread for every item thread.both(Producer, Consumer, &mut p, produce, &mut c, consume) A thread function takes a pointer to its argument, which the Thread owns until join returns the result. Channels, mutexes and atomics are values that threads share by pointer; the owner must join every thread using them before letting them go out of scope (each and both do it themselves), and call free when done. Panics inside a thread surface from join. Timeouts are in milliseconds, and 0 waits for ever.

Types: Task(T,, Thread(T,, WorkerTask(T){, Worker(T){, Channel(T){, Mutex(T){, Atomic

std.time#

std.time: dates, durations, time zones and timers, written in Nexium. import std.time then: let now = time.now_utc() // a DateTime println("{}", .{now.iso()}) // 2026-09-19T04:15:14.123Z println("{}", .{now.format("%Y-%m-%d %H:%M")}) let local = time.now_local() // with the machine's UTC offset let ny = try time.zone("America/New_York") // from the platform's database println("{}", .{ny.format(time.now(), "%H:%M %Z")}) // 00:15 EDT let d = time.Duration.minutes(90) println("{} {}", .{d.text(), d.iso()}) // 1h 30m PT1H30M var sw = time.Stopwatch.start() ... work ... println("took {}", .{sw.elapsed().text()}) Instants are milliseconds since 1970-01-01T00:00:00Z (time.now()), as i64; negative values are before the epoch. Calendar arithmetic is the proleptic Gregorian calendar. Time zones come from the platform's database: the zoneinfo files on Linux, macOS and the BSDs (under /usr/share/zoneinfo, or $TZDIR), ICU on Windows (10, version 1903 and later). now_local and local take only the local offset, from the C library; local_zone is the machine's zone with its history.

Types: DateTime, Duration, Period, RuleDay, Rule, Zone, Stopwatch

std.toml#

std.toml: TOML 1.0 (toml.io), written in Nexium: reading a document into values, finding a value by its key, and writing values back as TOML. import std.toml then: let doc = try toml.parse(text) let name = toml.as_str(toml.lookup(&doc, "package.name") orelse return) orelse "" for dep in toml.keys(toml.get(&doc, "dependencies") orelse return) { } if let why = toml.problem(text) { eprintln("{}", .{why}) } // "line 3: ..." let out = toml.stringify(&doc) Every value TOML has: strings (basic and literal, each also multi-line), 64-bit integers (decimal, hex, octal, binary), floats (with inf and nan), booleans, dates and times (kept as written: offset date-time, local date-time, local date, local time), arrays, tables, inline tables and arrays of tables, under TOML's rules that a key and a table are defined once. A document that breaks one is error.InvalidInput; problem says where and why.

Types: Toml, Entry, StampKind, Stamp

std.uuid#

std.uuid: UUIDs (RFC 9562), written in Nexium: random ones (version 4), ones that sort by the time they were made (version 7), and their text. import std.uuid then: let id = try uuid.v4() // 122 random bits println("{}", .{id.text()}) // "9f1c2e7a-4b3d-4e8f-a1b2-c3d4e5f60718" let row = try uuid.v7() // the time first: sorts by creation let back = uuid.parse(text) orelse return error.BadId The random bits come from random.secure, the operating system's generator, so an id cannot be guessed from the ones before it; v4 and v7 fail only where the system has no generator (IoError).

Types: Uuid

std.websocket#

std.websocket: a WebSocket client (RFC 6455), written in Nexium over std.http's transports. import std.websocket then: var ws = try websocket.connect("ws://localhost:8080/chat", 10000) try ws.send_text("hello") while true { let m = try ws.recv() // a whole message if m.op == websocket.CLOSE { break } // the server's close, or the end println("{}", .{m.data}) } ws.close(1000, "done") var gw = try websocket.connect_with(NxTls, &mut layer, "wss://gateway.discord.gg/?v=10", 10000) var api = websocket.socket(NxTls, &mut layer) // with headers of its own api.header("Authorization", token) try api.open("wss://example.com/stream", 10000) wss:// goes over a TLS layer, the slot std.http's client uses (http.Transport, which nxtls fills). No extensions are asked for (no compression). A message arrives whole, its fragments joined, up to max_message bytes; recv answers a ping with a pong on its way. The first protocol mistake by the server ends the connection, with the reason in problem. The handshake's key and every frame's mask come from random.secure. A recv that waits longer than the timeout is error.Timeout and may be called again: nothing that came is lost.

Types: Message, Decoder, Socket(T){