Skip to content

stdlib.serialize

Serialization Library

Generated from v0.65.7. 8 source files, 130 documented symbols.

csv.xi

fn csv_parse(text: Str) -> Result[Vec[Vec[Str]], Str]

Parse RFC 4180 CSV with the default comma delimiter.

  • Postcondition: (text.len() == 0) => (result.is_ok == true)
fn csv_parse_with(text: Str, delimiter: UInt8) -> Result[Vec[Vec[Str]], Str]

Parse RFC 4180 CSV with an explicit delimiter byte.

  • Precondition: delimiter != _CSV_QUOTE
  • Precondition: delimiter != _CSV_CR && delimiter != _CSV_LF
  • Postcondition: (text.len() == 0) => (result.is_ok == true)
fn csv_write_row(fields: &Vec[Str]) -> Str

Serialize one record (no trailing terminator), quoting as needed.

  • Postcondition: (fields.len() == 0) => (result == "")
  • Postcondition: result.len() >= fields.len() - 1
fn csv_write(rows: &Vec[Vec[Str]]) -> Str

Serialize records with CRLF terminators per RFC 4180.

  • Postcondition: (rows.len() == 0) => (result == "")
  • Postcondition: result.len() >= 2 * rows.len()

endian.xi

fn write_u16_le(out: &mut Vec[UInt8], v: UInt16)

Append v as two little-endian bytes (LSB first). Complexity: O(1).

  • Postcondition: out.len() == out.len()@pre + 2
fn write_u32_le(out: &mut Vec[UInt8], v: UInt32)

Append v as four little-endian bytes (LSB first). Complexity: O(1).

  • Postcondition: out.len() == out.len()@pre + 4
fn write_u64_le(out: &mut Vec[UInt8], v: UInt64)

Append v as eight little-endian bytes (LSB first). Complexity: O(1).

  • Postcondition: out.len() == out.len()@pre + 8
fn write_u16_be(out: &mut Vec[UInt8], v: UInt16)

Append v as two big-endian bytes (MSB first). Complexity: O(1).

  • Postcondition: out.len() == out.len()@pre + 2
fn write_u32_be(out: &mut Vec[UInt8], v: UInt32)

Append v as four big-endian bytes (MSB first). Complexity: O(1).

  • Postcondition: out.len() == out.len()@pre + 4
fn write_u64_be(out: &mut Vec[UInt8], v: UInt64)

Append v as eight big-endian bytes (MSB first). Complexity: O(1).

  • Postcondition: out.len() == out.len()@pre + 8
fn read_u16_le(data: &Vec[UInt8], pos: Int) -> UInt16

Read a little-endian UInt16 at pos; returns 0 when fewer than two bytes remain. Callers must verify pos + 2 <= data.len(). Complexity: O(1).

  • Postcondition: (pos < 0 || pos + 2 > data.len()) => (result == 0)
fn read_u32_le(data: &Vec[UInt8], pos: Int) -> UInt32

Read a little-endian UInt32 at pos; returns 0 when fewer than four bytes remain. Callers must verify pos + 4 <= data.len(). Complexity: O(1).

  • Postcondition: (pos < 0 || pos + 4 > data.len()) => (result == 0)
fn read_u64_le(data: &Vec[UInt8], pos: Int) -> UInt64

Read a little-endian UInt64 at pos; returns 0 when fewer than eight bytes remain. Callers must verify pos + 8 <= data.len(). Complexity: O(1).

  • Postcondition: (pos < 0 || pos + 8 > data.len()) => (result == 0)
fn read_u16_be(data: &Vec[UInt8], pos: Int) -> UInt16

Read a big-endian UInt16 at pos; returns 0 when fewer than two bytes remain. Callers must verify pos + 2 <= data.len(). Complexity: O(1).

  • Postcondition: (pos < 0 || pos + 2 > data.len()) => (result == 0)
fn read_u32_be(data: &Vec[UInt8], pos: Int) -> UInt32

Read a big-endian UInt32 at pos; returns 0 when fewer than four bytes remain. Callers must verify pos + 4 <= data.len(). Complexity: O(1).

  • Postcondition: (pos < 0 || pos + 4 > data.len()) => (result == 0)
fn read_u64_be(data: &Vec[UInt8], pos: Int) -> UInt64

Read a big-endian UInt64 at pos; returns 0 when fewer than eight bytes remain. Callers must verify pos + 8 <= data.len(). Complexity: O(1).

  • Postcondition: (pos < 0 || pos + 8 > data.len()) => (result == 0)
fn write_i64_le(out: &mut Vec[UInt8], v: Int)

Append v as eight little-endian two's-complement bytes. Complexity: O(1).

  • Postcondition: out.len() == out.len()@pre + 8
fn read_i64_le(data: &Vec[UInt8], pos: Int) -> Int

Read a little-endian signed 64-bit value at pos; returns 0 when fewer than eight bytes remain. Callers must verify pos + 8 <= data.len(). Complexity: O(1).

  • Postcondition: (pos < 0 || pos + 8 > data.len()) => (result == 0)
fn write_f64_le(out: &mut Vec[UInt8], v: Float64)

Append the IEEE-754 bit pattern of v little-endian (host byte order, which is little-endian on all supported targets). Complexity: O(1).

  • Precondition: true
  • Postcondition: out.len() == out.len()@pre + 8
fn read_f64_le(data: &Vec[UInt8], pos: Int) -> Float64

Read a little-endian IEEE-754 double at pos; returns 0.0 when fewer than eight bytes remain. Callers must verify pos + 8 <= data.len(). Complexity: O(1).

  • Postcondition: (pos < 0 || pos + 8 > data.len()) => (result == 0)

json.xi

enum JsonValue

NOTE: The parent module xiom.serialize is always present in the compile unit when any xiom.serialize.* submodule is used, and it defines its own JsonValue type (Object: Map[Str, JsonValue]). The compiler unifies the two same-named types, so this module MUST use the identical enum shape (Map-backed objects) or LLVM lowering fails.

  • Null
  • Bool(value: Bool)
  • Number(value: Float64)
  • String(value: Str)
  • Array(items: Vec[JsonValue])
  • Object(entries: Map[Str, JsonValue])
fn json_parse(s: Str) -> Result[JsonValue, Str]

Parse s into a JsonValue tree. Returns Err with a descriptive message on malformed input or trailing garbage, and for input nested deeper than the 128-level cap (_JSON_MAX_DEPTH). Complexity: O(n), n = input length.

NOTE: the name json_parse collides with the parent module's own json_parse and direct calls can misresolve under the current compiler (BUG 25 #1). The parsing logic lives in the uniquely-named helpers above. The Ok payload is a fresh main-heap JsonValue tree owned by the caller (R3): a direct let p = json_parse(s) binding reclaims it at scope exit.

  • Postcondition: (s.len() == 0) => (result.is_err == true)
  • Postcondition: (s == "null") => (result.is_ok == true)
fn json_stringify(v: JsonValue) -> Str

Serialize v as compact JSON (no insignificant whitespace). The by-value argument is CONSUMED for the call and not retained (R4): a proven-owned temporary from a builder's build() has its Vec/Map data buffers reclaimed after this call, while String leaves are borrowed and stay alive. A variable argument stays leak-only (no move proof). Complexity: O(n), n = number of nodes.

  • Postcondition: result.len() > 0
fn json_stringify_ref(v: &JsonValue) -> Str

Serialize v by reference as compact JSON. Callers that already hold a tree (PULSE request handlers) use this to avoid the by-value deep copy at the call boundary (REL-20261020-1704-pulse). Complexity: O(n), n = number of nodes.

  • Postcondition: result.len() > 0
fn json_pretty(v: JsonValue) -> Str

Serialize v as indented JSON (2 spaces per level). Complexity: O(n), n = number of nodes.

  • Postcondition: result.len() > 0
fn json_pretty_ref(v: &JsonValue) -> Str

Serialize v by reference as indented JSON. See json_stringify_ref. Complexity: O(n), n = number of nodes.

  • Postcondition: result.len() > 0
fn json_get(v: JsonValue, key: Str) -> Option[JsonValue]

The value under key, if v is an object and the key is present. Complexity: O(k), k = number of keys.

fn json_get_ref(v: &JsonValue, key: Str) -> Option[JsonValue]

The value under key by reference; only the found subtree is copied, not the whole input tree (REL-20261020-1704-pulse). Complexity: O(k), k = number of keys.

  • Precondition: true
fn json_get_path(v: JsonValue, path: &Vec[Str]) -> Option[JsonValue]

The value at a key path (e.g. ["user", "address", "city"]), navigating objects by string key and arrays by numeric string index. Complexity: O(d * k), d = path depth, k = keys per object.

  • Postcondition: (path.len() == 0) => (result.is_some == true)
fn json_set(v: JsonValue, key: Str, value: JsonValue) -> JsonValue

A copy of v (an object) with key set to value. An existing key is replaced; a missing key is appended. Complexity: O(k), k = number of keys.

  • Postcondition: json_type(result) == "object"
fn json_array_push(v: JsonValue, item: JsonValue) -> JsonValue

A copy of the array v with item appended. Non-array values produce an array containing just item. Complexity: O(k), k = number of items.

  • Postcondition: json_type(result) == "array"
fn json_object_new() -> JsonValue

A new empty JSON object. Complexity: O(1).

  • Postcondition: json_type(result) == "object"
type JsonObjectBuilder

In-place object builder: one Map, no copy per key. Call build() to return a JsonValue. Avoids the O(n^2) copy churn of json_set.

Field Type
entries Map[Str, JsonValue]
fn json_object_builder_new() -> JsonObjectBuilder

New empty JSON object builder.

  • Postcondition: result.entries.len() == 0
fn put(self: Self, key: Str, value: JsonValue)

Insert or replace one key in the object builder.

  • Postcondition: self.entries.contains(&key)
fn build(self: Self) -> JsonValue

Wrap the object builder's entries as a JSON object. The receiver is CONSUMED: the returned tree owns the Map's data buffers. R4 contract: a direct json_stringify(b.build()) reclaims those buffers after the call; literal keys and borrowed String values are never freed.

  • Postcondition: json_type(result) == "object"
type JsonArrayBuilder

In-place array builder: one Vec, no copy per item.

Field Type
items Vec[JsonValue]
fn json_array_builder_new() -> JsonArrayBuilder

New empty JSON array builder.

  • Postcondition: result.items.len() == 0
fn push(self: Self, item: JsonValue)

Append one item to the array builder.

  • Postcondition: self.items.len() >= 1
fn build(self: Self) -> JsonValue

Wrap the array builder's items as a JSON array. The receiver is CONSUMED: the returned tree owns the Vec data buffer. R4 contract: a direct json_stringify(a.build()) reclaims it after the call; borrowed String elements are never freed.

  • Postcondition: json_type(result) == "array"
fn json_array_new() -> JsonValue

A new empty JSON array. Complexity: O(1).

  • Postcondition: json_type(result) == "array"
fn json_number(f: Float64) -> JsonValue

Wrap a float as a JSON number. Complexity: O(1).

  • Postcondition: json_type(result) == "number"
fn json_string(s: Str) -> JsonValue

Wrap a string as a JSON string. Complexity: O(1).

  • Postcondition: json_type(result) == "string"
fn json_bool(b: Bool) -> JsonValue

Wrap a bool as a JSON bool. Complexity: O(1).

  • Postcondition: json_type(result) == "bool"
fn json_null() -> JsonValue

The JSON null value. Complexity: O(1).

  • Postcondition: json_type(result) == "null"
fn json_type(v: JsonValue) -> Str

The type name of v: object, array, string, number, bool, or null. Complexity: O(1).

  • Postcondition: result.len() >= 4
fn json_type_ref(v: &JsonValue) -> Str

The type name of v by reference, avoiding the by-value tree copy. Complexity: O(1).

  • Postcondition: result.len() >= 4
fn json_escape(s: Str) -> Str

Escape s for embedding inside a JSON string literal (without the surrounding quotes). Handles \" \ \/ \b \f \n \r \t and control chars. Complexity: O(n), n = string length.

NOTE: the name json_escape collides with the parent module's own json_escape; the logic lives in the uniquely-named _json_escape_impl.

  • Postcondition: (s.len() == 0) => (result == "")
  • Postcondition: result.len() >= s.len()
type JsonMemberSpan

Offsets of one object member in the source bytes: [key_start, key_end) is the raw key text without its quotes; [value_start, value_end) is the exact raw value (a string member includes its quotes and escape bytes).

Field Type
key_start Int
key_end Int
value_start Int
value_end Int
fn json_find_member(s: Str, key: Str) -> Result[JsonMemberSpan, Str]

Locate the first member named key in the top-level object of s and return its raw spans (offsets into s). Escape-aware key compare; malformed input yields a typed Err with the byte offset. Nested container values are bracket/string balanced (deep validation stays json_parse's job); duplicate keys report the first match. Complexity: O(n), n = bytes scanned up to the match.

  • Postcondition: (s.len() == 0) => (result.is_err == true)
fn json_raw_get(s: Str, key: Str) -> Result[Str, Str]

The exact raw value bytes of the first member named key, untouched by parsing (a string member keeps its quotes and escape bytes; a number keeps its formatting) -- the format-preserving lookup the packages relay asked for. Complexity: O(n), n = bytes scanned up to the match.

  • Postcondition: (s.len() == 0) => (result.is_err == true)
fn json_raw_get_str(s: Str, key: Str) -> Result[Str, Str]

The decoded value of a string member named key (escape-aware; surrogate pairs are combined, lone surrogates are rejected). Err when the member is missing, is not a string, or the member list is malformed. Complexity: O(n), n = bytes scanned up to and through the match.

  • Postcondition: (s.len() == 0) => (result.is_err == true)
fn json_raw_get_int(s: Str, key: Str) -> Result[Int, Str]

The value of an integer member named key. The raw token must be an optional '-' followed by ASCII digits (JSON integers, no fraction or exponent -- the flat-scanner shape vault/dynamo asked for); the parsed value is range-checked against Int. Complexity: O(n), n = bytes scanned up to and through the match.

  • Postcondition: (s.len() == 0) => (result.is_err == true)
fn json_as_str(v: JsonValue) -> Option[Str]

The Str payload of a JSON string value (None for every other type). Complexity: O(1).

  • Postcondition: (result.is_some == true) => (json_type(v) == "string")
fn json_as_bool(v: JsonValue) -> Option[Bool]

The Bool payload of a JSON bool value (None for every other type). Complexity: O(1).

  • Postcondition: (result.is_some == true) => (json_type(v) == "bool")
fn json_as_int(v: JsonValue) -> Option[Int]

The Int payload of a JSON number when it is exactly integer-valued and within +/-2^53 (None for non-numbers, fractional values, NaN, and unsafe magnitudes). The double bound keeps the conversion exact. Complexity: O(1).

  • Postcondition: (result.is_some == true) => (json_type(v) == "number")
fn json_as_float(v: JsonValue) -> Option[Float64]

The Float64 payload of a JSON number (None for every other type). Complexity: O(1).

  • Postcondition: (result.is_some == true) => (json_type(v) == "number")

serialize.xi

type SerializeError

=== Error type ===

Field Type
kind Int
message Str
path Str
line Int
col Int

Derives: Eq, Clone, Display

fn format_error() -> Str

Error kinds: 0=Unknown, 1=InvalidFormat, 2=MissingField, 3=TypeMismatch, 4=ContractViolation, 5=UnsupportedType

  • Postcondition: result.len() >= 15
  • Postcondition: (self.kind == 0 && self.message == "" && self.path == "" && self.line == 0 && self.col == 0) => (result == "SerializeError[0]: (line 0, col 0)")

fn detect_format(data: &Vec[UInt8]) -> Str

=== Format detection ===

  • Postcondition: result.len() > 0

fn is_valid_json(data: Str) -> Bool

True when the text parses as JSON.

  • Postcondition: (data.len() == 0) => (result == false)

fn is_valid_bytes(data: &Vec[UInt8]) -> Bool

True when the bytes contain valid UTF-8 JSON.

  • Postcondition: (data.len() == 0) => (result == false)

fn json_string(s: Str) -> Str

=== JSON helpers ===

  • Postcondition: (s.len() == 0) => (result == """")
  • Postcondition: result.len() >= s.len() + 2

fn json_number(n: Float64) -> Str

JSON number literal for the value.

  • Postcondition: (n != n) => (result == "nan")
  • Postcondition: (n == 0) => (result == "0")

fn json_bool(b: Bool) -> Str

JSON literal "true"/"false".

  • Postcondition: (b == true) => (result == "true")
  • Postcondition: (b == false) => (result == "false")

fn json_null() -> Str

JSON literal "null".

  • Postcondition: result == "null"

fn json_array(items: Vec[Str]) -> Str

JSON array from pre-rendered element strings.

  • Postcondition: (items.len() == 0) => (result == "[]")
  • Postcondition: result.len() >= 2 * items.len()

fn json_object(pairs: Vec[(Str, Str)]) -> Str

JSON object from pre-rendered key/value pairs.

  • Postcondition: (pairs.len() == 0) => (result == "{}")
  • Postcondition: result.len() >= 4 * pairs.len()

fn to_json[T](value: T) -> Result[Str, SerializeError]

Serialize a value to JSON; Err on failure.

fn from_json[T](s: Str) -> Result[T, SerializeError]

Deserialize a value from JSON; Err on failure.

fn json_parse(data: Str) -> Result[JsonValue, SerializeError]

Parse JSON text into a JsonValue; Err with position info. The Ok payload is a fresh main-heap JsonValue tree owned by the caller (R3): a direct let p = json_parse(s) binding reclaims it at scope exit.

  • Postcondition: (data.len() == 0) => (result.is_err == true)
  • Postcondition: (data == "null") => (result.is_ok == true)

fn parse_json(s: Str) -> Result[JsonValue, SerializeError]

Alias of json_parse (parse JSON text).

  • Postcondition: (s.len() == 0) => (result.is_err == true)

enum JsonValue

Parsed JSON value (null/bool/number/string/array/object).

  • Null
  • Bool(value: Bool)
  • Number(value: Float64)
  • String(value: Str)
  • Array(items: Vec[JsonValue])
  • Object(entries: Map[Str, JsonValue])

fn to_str(self: Self) -> Str

=== JsonValue methods ===

  • Postcondition: result.len() > 0

fn get(self: Self, key: Str) -> Option[JsonValue]

Object member by key, or None.

fn index(self: Self, i: Int) -> Option[JsonValue]

Array element by index, or None.

  • Postcondition: (i < 0) => (result.is_none == true)

fn little_endian() -> Bool

=== Binary helpers ===

  • Postcondition: result == true

fn big_endian() -> Bool

True when the target is big-endian (false on x86_64).

  • Postcondition: result == false

fn json_escape(s: Str) -> Str

JSON-escapes a string (without surrounding quotes). Handles \, ", \n, \r, \t, \b, \f. Complexity: O(n), n = string length. Wave 126: single-Vec builder over the cached (base, len) view (the previous concat-per-char loop was quadratic in scans and allocations).

  • Postcondition: (s.len() == 0) => (result == "")
  • Postcondition: result.len() >= s.len()

fn json_unescape(s: Str) -> Result[Str, Str]

Unescapes a JSON-escaped string (without surrounding quotes). Handles \, \", \/, \b, \f, \n, \r, \t, \uNNNN. Complexity: O(n), n = string length.

  • Postcondition: (s.len() == 0) => (result.is_ok == true)

fn json_minify(s: Str) -> Result[Str, Str]

Strips whitespace from JSON outside of strings. Complexity: O(n), n = input length.

  • Postcondition: (s.len() == 0) => (result.is_ok == true)
  • Postcondition: result is Ok(_) => result.len() <= s.len()

fn json_pretty(s: Str) -> Result[Str, Str]

Pretty-prints JSON with 2-space indentation. Uses a simple tokenizer-based approach that tracks nesting depth. Complexity: O(n), n = input length.

  • Postcondition: (s.len() == 0) => (result.is_ok == true)

fn json_get_path(json: Str, path: Str) -> Option[Str]

Navigates a JSON string using a dot-notation path (e.g. "a.b.0"). Returns the value at the path as a string, or None if not found. Complexity: O(n * p), n = JSON size, p = path depth.

  • Postcondition: (json.len() == 0) => (result.is_none == true)

fn json_type_of(s: Str) -> Str

Returns the JSON type of a string: "object", "array", "string", "number", "bool", "null", or "invalid". Complexity: O(1) -- reads only the first non-whitespace character.

  • Postcondition: (s.len() == 0) => (result == "invalid")
  • Postcondition: (s == "{}") => (result == "object")
  • Postcondition: (s == "true") => (result == "bool")

fn varint_encode(value: Int) -> Vec[UInt8]

Encodes an integer using unsigned LEB128 (Little Endian Base 128). Each byte uses 7 bits for data and the MSB as continuation flag. Complexity: O(log128(n)).

  • Postcondition: result.len() >= 1 && result.len() <= 10
  • Postcondition: (value == 0) => (result.len() == 1)
  • Postcondition: (value == 300) => (result.len() == 2)

fn varint_decode(data: &Vec[UInt8], pos: Int) -> Result[Int, Str]

Decodes an unsigned LEB128 integer from a byte slice starting at pos. Returns the decoded value. The caller advances pos by varint_encoded_len. Complexity: O(log128(n)).

  • Postcondition: (pos >= data.len()) => (result.is_err == true)

fn varint_decode_at(data: &Vec[UInt8], pos: Int) -> Result[Int, Str]

Decodes a LEB128 integer and returns the value with its encoded byte length. The caller can advance by the returned length. Complexity: O(log128(n)).

  • Postcondition: (pos >= data.len()) => (result.is_err == true)

fn varint_encoded_len(data: &Vec[UInt8], pos: Int) -> Int

Returns the number of bytes consumed by a LEB128-encoded integer. Scans continuation bits. Complexity: O(log128(n)).

  • Postcondition: (pos >= data.len()) => (result == 0)

fn bytes_to_hex_str(data: &Vec[UInt8]) -> Str

Converts bytes to a hex string. Delegates to xiom.encoding.hex_encode. Complexity: O(n), n = data length.

  • Postcondition: (data.len() == 0) => (result == "")
  • Postcondition: result.len() == 2 * data.len()

fn hex_str_to_bytes(s: Str) -> Result[Vec[UInt8], Str]

Converts a hex string to bytes. Delegates to xiom.encoding.hex_decode. Complexity: O(n), n = string length.

  • Postcondition: (s.len() == 0) => (result.is_ok == true)

toml.xi

enum TomlValue

TOML v1 reader (the subset a package manifest needs).

Supported: comments; bare and quoted keys; [table] and [a.b] headers; basic strings with the five common escapes; literal strings; integers (decimal, optional sign, _ separators); floats; booleans; arrays of strings/ints/floats. Keys are stored section-qualified with '.' ("package.name"), in file order.

NOT in v1: dates/times, multi-line strings, inline tables, arrays-of-tables, dotted keys in assignment position. The WRITER (toml_write) emits the same subset: flat section-qualified keys, root keys first, [section] blocks in first-appearance order, the five common escapes. Errors carry the 1-based line number.

  • TStr(_0: Str)
  • TInt(_0: Int)
  • TFloat(_0: Float64)
  • TBool(_0: Bool)
  • TStrArray(_0: Vec[Str])
  • TIntArray(_0: Vec[Int])
  • TFloatArray(_0: Vec[Float64])
type TomlTable

Parsed TOML table (ordered key -> value map).

Field Type
keys Vec[Str]
values Vec[TomlValue]
fn toml_parse(text: Str) -> Result[TomlTable, Str]

Parse a TOML v1 subset document; keys are section-qualified ("a.b"). Errors carry the 1-based source line.

  • Postcondition: (text.len() == 0) => (result.is_ok == true)
  • Postcondition: (text == "a = 1") => (result.is_ok == true)
  • Postcondition: (text == "[a") => (result.is_err == true)
fn toml_get(t: &TomlTable, key: Str) -> Option[TomlValue]

Value for key, or None when missing.

  • Postcondition: (t.keys.len() == 0) => (result.is_none == true)
fn toml_has(t: &TomlTable, key: Str) -> Bool

True when key exists.

  • Postcondition: (t.keys.len() == 0) => (result == false)
fn toml_get_str(t: &TomlTable, key: Str) -> Option[Str]

String value for key, or None when missing or of another type.

  • Postcondition: (t.keys.len() == 0) => (result.is_none == true)
fn toml_get_int(t: &TomlTable, key: Str) -> Option[Int]

Int value for key, or None when missing or of another type.

  • Postcondition: (t.keys.len() == 0) => (result.is_none == true)
fn toml_get_float(t: &TomlTable, key: Str) -> Option[Float64]

Float value for key, or None when missing or of another type.

  • Postcondition: (t.keys.len() == 0) => (result.is_none == true)
fn toml_get_bool(t: &TomlTable, key: Str) -> Option[Bool]

Bool value for key, or None when missing or of another type.

  • Postcondition: (t.keys.len() == 0) => (result.is_none == true)
fn toml_get_str_array(t: &TomlTable, key: Str) -> Option[Vec[Str]]

String-array value for key, or None when missing or of another type.

  • Postcondition: (t.keys.len() == 0) => (result.is_none == true)
fn toml_get_int_array(t: &TomlTable, key: Str) -> Option[Vec[Int]]

Int-array value for key, or None when missing or of another type.

  • Postcondition: (t.keys.len() == 0) => (result.is_none == true)
fn toml_keys(t: &TomlTable) -> Vec[Str]

All keys in file order.

  • Postcondition: result.len() == t.keys.len()
fn toml_write(t: &TomlTable) -> Str

Render t as TOML text for the v1 subset: root keys first (file order), then one [section] block per dotted-key prefix, in first-appearance order. Round-trips through toml_parse except for non-finite floats (written as nan/inf, which the v1 reader does not accept back). Complexity: O(n^2) worst case in the number of keys (section grouping).

  • Postcondition: (t.keys.len() == 0) => (result == "")
  • Postcondition: result.len() >= t.keys.len()

varint.xi

fn varint_encode(value: Int) -> Vec[UInt8]

Encode value as signed LEB128 bytes (negative values use the 64-bit two's-complement pattern). Complexity: O(log128(|value|)).

  • Postcondition: result.len() >= 1 && result.len() <= 10
  • Postcondition: (value == 0) => (result.len() == 1)
  • Postcondition: (value == 300) => (result.len() == 2)
fn varint_decode(bytes: &Vec[UInt8]) -> Result[(Int, Int), Str]

Decode a signed LEB128 value from bytes, returning (value, consumed). Returns Err on truncation or on input longer than 10 bytes. Complexity: O(1) (at most 10 bytes).

NOTE: the name varint_decode collides with the parent module xiom.serialize's own varint_decode, so direct calls to this symbol can misresolve in the current compiler (BUG 25 #1). The real logic lives in the uniquely-named private helper _sleb128_decode; this function is a thin wrapper. Prefer varint_decode_slice / _sleb128_decode for verification.

  • Postcondition: (bytes.len() == 0) => (result.is_err == true)
fn varint_size(value: Int) -> Int

The number of bytes needed to encode value as signed LEB128. Complexity: O(1) (at most 10).

  • Postcondition: result >= 1 && result <= 10
  • Postcondition: (value == 0) => (result == 1)
  • Postcondition: (value == 300) => (result == 2)
fn zigzag_encode(n: Int) -> Int

Map a signed value to its non-negative zigzag encoding: 0 -> 0, -1 -> 1, 1 -> 2, -2 -> 3, ... Complexity: O(1).

  • Postcondition: result == ((n << 1) ^ (n >> 63))
fn zigzag_decode(n: Int) -> Int

Invert zigzag_encode: map a zigzag value back to the signed value. Complexity: O(1).

  • Postcondition: result == ((n >> 1) ^ (0 - (n & 1)))
fn uvarint_encode(value: UInt64) -> Vec[UInt8]

Encode a UInt64 as unsigned LEB128 bytes. Complexity: O(log128(v)).

  • Postcondition: result.len() >= 1 && result.len() <= 10
  • Postcondition: (value == 0) => (result.len() == 1)
fn uvarint_decode(bytes: &Vec[UInt8]) -> Result[(UInt64, Int), Str]

Decode an unsigned LEB128 value from bytes, returning (value, consumed). Returns Err on truncation, on input longer than 10 bytes, or when the value would overflow UInt64. Complexity: O(1) (at most 10 bytes).

  • Postcondition: (bytes.len() == 0) => (result.is_err == true)
fn varint_encode_slice(values: &Vec[Int]) -> Vec[UInt8]

Encode each value back-to-back as a signed LEB128 stream.

  • Postcondition: (values.len() == 0) => (result.len() == 0)
  • Postcondition: result.len() >= values.len()
fn varint_decode_slice(bytes: &Vec[UInt8]) -> Result[Vec[Int], Str]

Decode a stream of back-to-back signed LEB128 values. Returns Err on the first malformed or truncated varint. Complexity: O(n), n = number of values.

  • Postcondition: (bytes.len() == 0) => (result.is_ok == true)

xml.xi

type XmlAttr

One attribute of a start tag. value is the entity-decoded text between the quotes (the quotes themselves are not part of it).

Field Type
name Str
value Str
type XmlTag

A start tag: its name, attributes in document order, and whether the tag was explicitly closed with />.

Field Type
name Str
attrs Vec[XmlAttr]
self_closing Bool
enum XmlToken

One lexical XML token.

Payloads: - Prolog / ProcessingInstruction / Doctype: the raw text between the delimiters (no entity decoding; DOCTYPE includes its internal subset); - StartTag: the tag with its attributes (attribute values decoded); - EndTag: the tag name; - Text / Comment / CData: the content (Text is entity-decoded, Comment and CData are raw); - Eof: end of input.

  • Prolog(content: Str)
  • ProcessingInstruction(content: Str)
  • Doctype(content: Str)
  • StartTag(tag: XmlTag)
  • EndTag(name: Str)
  • Text(value: Str)
  • Comment(value: Str)
  • CData(value: Str)
  • Eof
type XmlTokenizer

Streaming tokenizer state. Create it with xml_tokenizer_new, then pull tokens with xml_next until XmlToken.Eof (or Err).

Fields: src is the whole document, pos the next unread byte offset, failed/err latch the first error so a broken stream can never yield a token after its Err.

Field Type
src Str
pos Int
failed Bool
err Str
fn xml_tokenizer_new(s: Str) -> XmlTokenizer

Create a streaming tokenizer over s. Complexity: O(1); no bytes are scanned until the first xml_next call.

  • Postcondition: result.pos == 0
fn xml_next(t: &mut XmlTokenizer) -> Result[XmlToken, Str]

Pull the next token. Returns XmlToken.Eof at the end of input and a typed Err (with a byte offset) on malformed input; after an Err every further call returns the same Err (the tokenizer latches). Complexity: O(k), k = bytes consumed by this token.

  • Postcondition: (result.is_err == true) => (t.failed == true)
fn xml_tokenize(s: Str) -> Result[Vec[XmlToken], Str]

Tokenize the whole document into a Vec (without the trailing Eof token). Returns Err on the first malformed construct. Complexity: O(n), n = input length.

  • Postcondition: (s.len() == 0) => (result.is_ok == true)
fn xml_token_kind(t: XmlToken) -> Str

The token kind name: "prolog", "processing_instruction", "doctype", "start_tag", "end_tag", "text", "comment", "cdata", or "eof". Complexity: O(1).

  • Postcondition: result.len() >= 3
fn xml_attr_get(tag: &XmlTag, name: Str) -> Option[Str]

The first attribute named name on tag (names are case-sensitive). Complexity: O(a), a = attribute count.

  • Postcondition: (name.len() == 0) => (result.is_none == true)
fn xml_decode_entities(s: Str) -> Result[Str, Str]

Decode the predefined XML entities (& < > " ') and numeric character references ({ / ) in s. Raw text outside references passes through. Returns Err on a bare '&', an unknown or malformed reference, or an invalid XML character. Complexity: O(n), n = string length.

  • Postcondition: (s.len() == 0) => (result.is_ok == true)

yaml_lite.xi

enum YamlValue

Parsed YAML-lite value (scalar/map/sequence).

  • Scalar(value: Str)
  • Sequence(items: Vec[YamlValue])
  • Mapping(keys: Vec[Str], values: Vec[YamlValue])
fn yaml_parse(s: Str) -> Result[YamlValue, Str]

Parse s into a YamlValue tree. Returns Err on malformed documents. Complexity: O(n), n = document size.

NOTE: the current compiler miscompiles cross-module calls that return a Result whose payload is a recursive enum (see report); yaml_parse works when invoked from within its own module but not across modules.

  • Postcondition: (s.len() == 0) => (result.is_err == true)
  • Postcondition: (s == "a: 1") => (result.is_ok == true)
fn yaml_parse_document(s: Str) -> Result[YamlValue, Str]

Parse a single YAML document (alias of yaml_parse for a strict reader). Complexity: O(n), n = document size.

  • Postcondition: (s.len() == 0) => (result.is_err == true)
  • Postcondition: (s == "a: 1") => (result.is_ok == true)
fn yaml_stringify(v: YamlValue) -> Str

Serialize v as YAML text. Complexity: O(n), n = number of nodes.

fn yaml_get(v: YamlValue, key: Str) -> Option[YamlValue]

The value under key, if v is a mapping and the key is present. Complexity: O(k), k = number of keys.

fn yaml_emit_scalar(s: Str) -> Str

Emit s as a quoted (when ambiguous) or plain YAML scalar. Complexity: O(n), n = string length.

  • Postcondition: (s.len() == 0) => (result == """")
  • Postcondition: result.len() >= s.len()
fn yaml_emit_sequence(items: &Vec[Str]) -> Str

Emit items as a YAML block sequence. Complexity: O(n), n = number of items.

  • Postcondition: (items.len() == 0) => (result == "")
  • Postcondition: result.len() >= items.len()
fn yaml_emit_mapping(keys: &Vec[Str], values: &Vec[Str]) -> Str

Emit keys and values as a YAML block mapping. The two vectors must be the same length; mismatches are truncated to the shorter. Complexity: O(n), n = number of keys.

  • Postcondition: (keys.len() == 0 || values.len() == 0) => (result == "")