Module

std::toml::value

TOML Values

Owned TOML document, table, array, and scalar value model.

Overview

The value layer stores parsed TOML data in owned Ignis records and provides lookup helpers for dotted paths. Tables preserve explicit table state so the parser can distinguish duplicate keys, table conflicts, and arrays of tables.

Records

record TomlArray

Ordered TOML array value.

TomlArray stores cloned TomlValue entries in a manually managed growable buffer. It is intentionally separate from Vector<TomlValue> so the parser can control cloning and recursive value storage explicitly.

Members
values: *mut TomlValue

Pointer to the array element storage.

length(&self): u64

Returns the number of initialized array values.

capacity: u64

Number of value slots currently allocated.

span: TomlSpan

Source span covering the array expression.

static new(span: TomlSpan): TomlArray

Creates an empty TOML array with the given source span.

grow(&mut self): void

Grows the backing storage using geometric doubling.

Capacity starts at 1 and doubles whenever push would exceed the current allocation.

item(&self, index: u64): Option<TomlValue>

Returns a cloned value at index when it exists.

Returns

Option::SOME(value) for in-bounds indices, otherwise Option::NONE.

length(&self): u64

Returns the number of initialized array values.

push(&mut self, value: TomlValue): void

Appends a cloned TOML value to the array.

Arguments

  • value: value to clone into array storage.
record TomlArrayOfTables

TOML array-of-tables container.

Each entry is a full TomlTable corresponding to one [[table]] header. Entries preserve parse order.

Members
entries: *mut TomlTable

Pointer to table entry storage.

length(&self): u64

Returns the number of stored table entries.

capacity: u64

Number of allocated table slots.

span: TomlSpan

Source span for the array-of-tables header or container.

static new(span: TomlSpan): TomlArrayOfTables

Creates an empty array-of-tables container.

grow(&mut self): void

Grows table storage using geometric doubling.

item(&self, index: u64): Option<TomlTable>

Returns a table entry by index.

lastPointer(&mut self): Option<*mut TomlTable>

Returns a mutable pointer to the last table entry.

Parser code uses this to append assignments to the most recent array table.

length(&self): u64

Returns the number of stored table entries.

push(&mut self, value: TomlTable): void

Appends a table entry.

record TomlDateTime

Structured TOML date/time value.

The parser keeps both the raw source representation and parsed numeric fields. Fields that do not apply to the selected kind are set to zero. offsetMinutes is zero for local date/time values.

Members
raw: str

TOML-owned raw literal text.

kind: TomlDateTimeKind

Classified datetime shape.

year: i32

Four-digit year for date-bearing values, or 0 for local time.

month: i32

Month number for date-bearing values, or 0 for local time.

day: i32

Day number for date-bearing values, or 0 for local time.

hour: i32

Hour component for time-bearing values.

minute: i32

Minute component for time-bearing values.

second: i32

Second component for time-bearing values.

fractionalDigits: i32

Number of fractional second digits preserved from the literal.

offsetMinutes: i32

UTC offset in minutes for offset datetimes.

span: TomlSpan

Source span of the datetime literal.

static empty(): TomlDateTime

Returns the zero/default datetime used by inactive TomlValue payloads.

TomlValue is a tagged record rather than a union; inactive datetime storage is filled with this value.

static localDate(raw: str, year: i32, month: i32, day: i32, span: TomlSpan): TomlDateTime

Creates a local date value with zeroed time fields.

Example

let date: TomlDateTime = TomlDateTime::localDate("1979-05-27", 1979, 5, 27, TomlSpan::new(0, 10));
static new(raw: str, kind: TomlDateTimeKind, year: i32, month: i32, day: i32, hour: i32, minute: i32, second: i32, fractionalDigits: i32, offsetMinutes: i32, span: TomlSpan): TomlDateTime

Creates a structured datetime with explicit components.

Arguments

  • raw: original TOML literal text.
  • kind: datetime category.
  • numeric fields: parsed date/time/offset components.
  • span: source span for diagnostics.
static offsetDateTime(raw: str, year: i32, month: i32, day: i32, hour: i32, minute: i32, second: i32, fractionalDigits: i32, offsetMinutes: i32, span: TomlSpan): TomlDateTime

Creates an offset datetime value.

This is a convenience wrapper around TomlDateTime::new that fixes the kind to OFFSET_DATE_TIME.

clone(&self): TomlDateTime

Clones this datetime value.

The raw str pointer is copied as-is because it points at TOML-owned immutable storage.

record TomlDocument

Parsed TOML document rooted at a table.

Document lookup helpers accept dotted paths such as package.name and return typed lookup results with TOML spans when a path is missing or has the wrong value kind.

Members
root: TomlTable

Root TOML table.

span: TomlSpan

Source span covering the parsed document.

static new(root: TomlTable, span: TomlSpan): TomlDocument

Creates a document from a root table and source span.

get(&self, path: str): Option<TomlValue>

Returns a value at a dotted path, discarding lookup error details.

Use this when absence and type mismatch should both be treated as a simple missing optional value.

Example

let name: Option<TomlValue> = document.get("package.name");
getArray(&self, path: str): Result<TomlArray, TomlError>

Returns an array value at a dotted path.

Returns

  • Result::OK(TomlArray) when the path exists and resolves to an array.
  • LOOKUP_NOT_FOUND when any path segment is missing.
  • LOOKUP_TYPE_MISMATCH when the final value is not an array.
getString(&self, path: str): Result<str, TomlError>

Returns a string value at a dotted path.

Returns

  • Result::OK(str) when the path exists and resolves to a TOML string.
  • LOOKUP_NOT_FOUND when any path segment is missing.
  • LOOKUP_TYPE_MISMATCH when the final value is not a string.

Example

let name: Result<str, TomlError> = document.getString("package.name");
lookupValue(&self, path: str): Result<TomlValue, TomlError>

Resolves a borrowed dotted path into a TOML value.

lookupValue(&self, path: str): Result<TomlValue, TomlError>

Resolves a borrowed dotted path into a TOML value.

record TomlParserCursor

Cursor over a TOML token stream used by parser tests and parser helpers.

The cursor is a lightweight view into a Vector<TomlToken>. It does not own the token memory; callers must keep the source vector alive while the cursor is used.

Cursor Model

  tokens:  [IDENTIFIER][EQUALS][STRING][EOF]
            index=0

  advance() -> IDENTIFIER, index=1
  peekKind() -> EQUALS, index stays 1
Members
tokens: *mut TomlToken

Borrowed pointer to token storage owned by a Vector<TomlToken>.

length: u64

Number of tokens available through tokens.

index: u64

Current cursor index.

static create(tokens: &Vector<TomlToken>): TomlParserCursor

Creates a cursor over a token vector.

Arguments

  • tokens: token vector to view. It must outlive the cursor.

Returns

A cursor positioned at index 0.

Example

let cursor: TomlParserCursor = TomlParserCursor::create(&tokens);
advance(&mut self): Option<TomlTokenKind>

Consumes the current token and returns its kind.

If the cursor is already past the stream, the index is unchanged and the result is Option::NONE.

expect(&mut self, kind: TomlTokenKind): Result<TomlSpan, TomlError>

Requires the current token to have a specific kind and consumes it.

Returns

Result::OK(span) with the consumed token span on success, or Result::ERROR(TomlError::unexpectedToken(...)) when the stream is empty or the current token has a different kind.

isAtEnd(&self): boolean

Returns whether the cursor is positioned at the logical end of input.

A missing token or an explicit EOF token both count as end-of-input.

matchKind(&mut self, kind: TomlTokenKind): boolean

Consumes the current token only if it has the requested kind.

Returns

true when a token was consumed, otherwise false.

peekKind(&self): Option<TomlTokenKind>

Returns the kind of the current token without advancing.

Returns Option::NONE when the cursor has no token storage or has moved past the end of the token stream.

peekLexeme(&self): Option<str>

Returns the current token lexeme without advancing.

The returned str borrows from the token’s owned String. It remains valid as long as the underlying token vector is alive.

peekSpan(&self): Option<TomlSpan>

Returns the current token span without advancing.

Use this for diagnostics that need to report the lookahead token.

previousSpan(&self): TomlSpan

Returns the span of the previously consumed token.

At the beginning of the stream there is no previous token, so this returns an empty zero span.

skipNewlines(&mut self): void

Consumes consecutive NEWLINE tokens.

TOML parsing uses newlines as statement separators. This helper centralizes the common pattern of allowing blank lines between table headers and assignments.

tokenSpan(&self): TomlSpan

Returns a diagnostic span for the current cursor position.

If the cursor is at EOF or past the end, the last token span is used as a fallback so errors still point near the source location that ended parsing.

record TomlPathSegment

One segment of a dotted TOML path plus its source span.

For package.metadata.name, each segment stores the segment text and the source range that produced it. Parser diagnostics use the span for duplicate key and table conflict errors.

Members
text: str

TOML-owned segment text.

span: TomlSpan

Source span of this segment.

static new(text: &String, span: TomlSpan): TomlPathSegment

Creates a path segment by copying text into TOML-owned storage.

Arguments

  • text: segment text without dots.
  • span: source span for this segment.
record TomlTable

TOML key/value table.

Tables store entries in insertion order. The parser uses state to validate duplicate table declarations and conflicts between scalar values and tables.

Members
entries: *mut TomlTableEntry

Pointer to table entry storage.

length: u64

Number of initialized entries.

capacity: u64

Number of allocated entry slots.

span: TomlSpan

Source span for this table.

state: TomlTableState

Whether this table is implicit, explicit, or inline.

static new(span: TomlSpan): TomlTable

Creates an empty implicit table.

entryForKeyPointer(&mut self, key: &String): Option<*mut TomlTableEntry>

Looks up a mutable pointer to a table entry by key.

Parser code uses this to mutate existing implicit tables while building dotted paths and arrays of tables.

grow(&mut self): void

Grows table entry storage using geometric doubling.

insert(&mut self, key: str, value: TomlValue, keySpan: TomlSpan): void

Inserts a value by borrowed key text.

This method does not reject duplicates; parser validation performs conflict checks before insertion.

insert(&mut self, key: str, value: TomlValue, keySpan: TomlSpan): void

Inserts a value by borrowed key text.

This method does not reject duplicates; parser validation performs conflict checks before insertion.

pushEntry(&mut self, entry: TomlTableEntry): void

Appends a pre-built table entry.

valueForKey(&self, key: &String): Option<TomlValue>

Looks up a table value by key.

Returns

A cloned TomlValue when the key exists, otherwise Option::NONE.

record TomlTableEntry

Single key/value entry in a TOML table.

Members
key: str

TOML-owned key text.

value: TomlValue

Stored value for this key.

keySpan: TomlSpan

Source span of the key.

static create(key: &String, value: TomlValue, keySpan: TomlSpan): TomlTableEntry

Creates an entry from an owned key string reference.

static new(key: str, value: TomlValue, keySpan: TomlSpan): TomlTableEntry

Creates an entry from a borrowed key string.

record TomlValue

Tagged TOML value with scalar, array, table, and datetime payloads.

TomlValue uses a manual tagged representation: kind identifies the active payload and the remaining fields contain defaults or pointers to heap-owned nested structures. Arrays and tables are stored indirectly to avoid recursive value-by-value record layout.

Members
kind(&self): TomlValueKind

Returns the active payload kind.

span: TomlSpan

Source span of the value literal or composite value.

keySpan: TomlSpan

Source span of the key that introduced this value.

stringValue: str

Active when kind == TomlValueKind::STRING.

integerValue: i64

Active when kind == TomlValueKind::INTEGER.

floatValue: f64

Active when kind == TomlValueKind::FLOAT.

booleanValue: boolean

Active when kind == TomlValueKind::BOOLEAN.

arrayValue: *mut TomlArray

Heap pointer active when kind == TomlValueKind::ARRAY.

tableValue: *mut TomlTable

Heap pointer active when kind == TomlValueKind::TABLE.

arrayOfTablesValue: *mut TomlArrayOfTables

Heap pointer active when kind == TomlValueKind::ARRAY_OF_TABLES.

dateTimeValue: TomlDateTime

Active when kind == TomlValueKind::DATE_TIME.

static array(value: TomlArray, span: TomlSpan, keySpan: TomlSpan): TomlValue

Creates an array value by storing the array behind a heap pointer.

Arrays are recursive containers, so TomlValue stores them indirectly.

static arrayOfTables(value: TomlArrayOfTables, span: TomlSpan, keySpan: TomlSpan): TomlValue

Creates an array-of-tables value by storing entries behind a heap pointer.

static dateTime(value: TomlDateTime, span: TomlSpan, keySpan: TomlSpan): TomlValue

Creates a datetime scalar value.

static float(value: f64, span: TomlSpan, keySpan: TomlSpan): TomlValue

Creates a floating-point value.

static fromBoolean(value: boolean, span: TomlSpan, keySpan: TomlSpan): TomlValue

Creates a boolean value.

static integer(value: i64, span: TomlSpan, keySpan: TomlSpan): TomlValue

Creates an integer value.

static string(value: str, span: TomlSpan, keySpan: TomlSpan): TomlValue

Creates a string value and copies the text into TOML-owned storage.

static table(value: TomlTable, span: TomlSpan, keySpan: TomlSpan): TomlValue

Creates a table value by storing the table behind a heap pointer.

asArray(&self): Option<TomlArray>

Returns the array payload when this value is a TOML array.

asArrayOfTables(&self): TomlArrayOfTables

Returns the array-of-tables payload.

This accessor assumes the active kind is ARRAY_OF_TABLES; check kind() before calling it when handling arbitrary values.

asBoolean(&self): boolean

Returns the boolean payload.

Callers should check kind() first. Inactive boolean storage is false.

asDateTime(&self): Option<TomlDateTime>

Returns the datetime payload when this value is a TOML datetime scalar.

asFloat(&self): f64

Returns the float payload.

Callers should check kind() first. Inactive scalar fields contain default values, so this method does not distinguish type mismatches by itself.

asInteger(&self): i64

Returns the integer payload.

Callers should check kind() first. Inactive scalar fields contain default values, so this method does not distinguish type mismatches by itself.

asString(&self): Option<str>

Returns the string payload when this value is a TOML string.

asTable(&self): Option<TomlTable>

Returns the table payload when this value is a TOML table.

clone(&self): TomlValue

Clones this value.

Scalar payloads are copied directly. Nested array/table payload pointers are copied shallowly because parsed TOML documents treat nested values as stable immutable storage after construction.

kind(&self): TomlValueKind

Returns the active payload kind.

Enums

enum TomlDateTimeKind

Structured datetime category recognized by the TOML parser.

TOML has several date/time shapes. The parser preserves the original raw text and also records the classified shape for callers that need to distinguish local dates from offset datetimes.

Members
LOCAL_DATE
LOCAL_TIME
LOCAL_DATE_TIME
OFFSET_DATE_TIME
enum TomlTableState

Parser state for a TOML table definition.

This state lets the parser distinguish tables created implicitly by dotted keys from tables explicitly declared by [table] or inline table syntax.

Members
IMPLICIT
EXPLICIT
INLINE
enum TomlValueKind

Runtime kind tag for TomlValue.

TomlValue stores all possible payload fields in one record and uses this tag to identify which payload is active. Accessors such as asString and asArray check this tag before returning typed data.

Members
STRING
INTEGER
FLOAT
BOOLEAN
ARRAY
TABLE
ARRAY_OF_TABLES
DATE_TIME

Functions

function __closure_thunk_0(__closure_env_0: *mut u8, byte: u8): boolean
function tomlArrayOfTablesPointer(value: TomlArrayOfTables): *mut TomlArrayOfTables

Allocates one TomlArrayOfTables and writes value into it.

function tomlArrayPointer(value: TomlArray): *mut TomlArray

Allocates one TomlArray and writes value into it.

function tomlLookupInTable(table: &TomlTable, segments: &Vector<String>, index: u64, fallbackSpan: TomlSpan): Result<TomlValue, TomlError>

Recursively resolves dotted path segments inside a TOML table.

Arguments

  • table: current table to inspect.
  • segments: split path segments.
  • index: current segment index.
  • fallbackSpan: span used when lookup fails before a more specific span is available.

Returns

Result::OK(value) when the full path resolves, otherwise a lookup error.

function tomlOwnedStr(value: &String): str

Copies a String into TOML-owned NUL-terminated storage.

This helper is used by tokens, values, and table entries that need to store a stable str after parser-local String values go out of scope. The memory is allocated with Memory::allocateVector<u8> and is intentionally not reclaimed by the TOML value model yet.

Arguments

  • value: owned string whose bytes should be copied.

Returns

A str view into newly allocated storage with a trailing NUL byte.

Memory Layout

  input bytes: [p][k][g]
  allocated:   [p][k][g][\0]
                        ▲
                        C-string terminator for str interop
function tomlOwnedStr(value: &String): str

Copies a String into TOML-owned NUL-terminated storage.

This helper is used by tokens, values, and table entries that need to store a stable str after parser-local String values go out of scope. The memory is allocated with Memory::allocateVector<u8> and is intentionally not reclaimed by the TOML value model yet.

Arguments

  • value: owned string whose bytes should be copied.

Returns

A str view into newly allocated storage with a trailing NUL byte.

Memory Layout

  input bytes: [p][k][g]
  allocated:   [p][k][g][\0]
                        ▲
                        C-string terminator for str interop
function tomlPathSegments(path: &String): Vector<String>

Splits a dotted TOML lookup path into owned string segments.

Lookup helpers use this for public "a.b.c" path APIs. It performs a simple byte split on . and does not implement quoted-key escaping; callers that need exact TOML syntax should use parsed document paths instead.

function tomlTablePointer(value: TomlTable): *mut TomlTable

Allocates one TomlTable and writes value into it.

function tomlUnexpectedParserSpan(tokens: *mut TomlToken, length: u64, index: u64): TomlSpan

Returns the best diagnostic span for a parser cursor position.

Parser cursors may point at EOF or one position past the last real token. This helper keeps error reporting stable by using the requested token span when available, or the last token span as a fallback.

Arguments

  • tokens: pointer to the first token in the stream.
  • length: number of tokens in the stream.
  • index: cursor index that triggered an error.

Returns

A stable span for diagnostics. Empty streams return TomlSpan::new(0, 0).