std.toml

parse accepts a complete TOML 1.0 document. An empty document or comments with whitespace produce an empty root table. Basic and literal strings, multiline strings, dotted and quoted keys, inline tables, arrays and arrays of tables retain their TOML meanings.

Integers must fit the signed 64 bit range. TOML decimal, hexadecimal, octal and binary spellings and valid underscore separators are accepted. Floating values use IEEE binary64 rounding. The TOML inf and nan forms are valid TOML values. Finite overflow follows the TOML numeric error boundary and returns Err.

Offset date times, local date times, local dates and local times remain distinct TOML kinds. Invalid calendar fields and time fields return Err. Strings that resemble dates remain strings.

A key or table definition may not redefine an existing value under the TOML 1.0 rules. Names are compared after decoding. Malformed escapes, leading zeroes and misplaced underscore separators return Err without exposing a partial document.

A failure returns a nonempty string identifying the cause, one based line and Unicode scalar column. CRLF is a single line break. The first offending scalar is the location and an incomplete input points immediately after its last scalar. Source comments and layout are not retained in TOMLValue.

The text argument is evaluated once. Parsing consumes the complete document, performs no I/O and does not invoke JSON conversion. Syntax failures use Err rather than a runtime diagnostic.

stringify accepts a TOMLValue whose root is a table. A scalar or array root returns Err because it is not a TOML document. An empty table becomes empty text.

Each table writes its scalar and array entries before child table sections. Both groups follow the decoded key order →. Arrays retain element order. Table headers use the complete dotted path. A noninitial table section is separated by one blank line.

Assignments use one space on either side of the equals sign. Inline arrays and tables use a comma followed by one space. Every nonempty document uses LF line endings and ends with one LF. Comments, indentation and source ordering are not reproduced.

Bare keys use the TOML ASCII key alphabet. Other keys and string values use basic quoted strings with deterministic escaping. Integers use decimal digits without separators. Finite floats use the shortest binary64 roundtrip value and retain a decimal point or exponent to distinguish a float from an integer. Positive and negative zero are written as 0.0 and -0.0. Nonfinite values use inf, -inf or nan.

Dates and times use their TOML kind, a capital T separator and a capital Z for a zero offset. Local kinds retain their lack of an offset. Fractional seconds omit redundant trailing zeroes.

The value argument is evaluated once. Serialization performs no I/O, does not mutate the value and returns Err without partial output when the value cannot form a document. Parse the result with toml.parse to recover the same TOML kinds and values.

fromJson recursively converts a JSONValue into a TOMLValue and returns Result<TOMLValue, string>. Booleans, strings, arrays and objects retain their values and structure. JSON null has no TOML representation and returns Err, including a nested null.

An integer lexeme must fit signed 64 bit and becomes a TOML integer. An out of range integer returns Err rather than changing into a float. A fractional or exponent lexeme becomes binary64 with nearest ties to even rounding. Overflow to infinity returns Err. Finite rounding and underflow may change the exact decimal value.

A string is kept as a string even when it resembles a date or time. Converting a JSON scalar or array is permitted, but writing it as a complete TOML document still requires a root table.

TOMLValue.toJson() -> Result<JSONValue, string> recursively converts a TOML value. Tables become objects and arrays retain order. Finite numbers follow JSON numeric conversion →. Nonfinite numbers return Err rather than becoming a string or null.

TOML dates and times become strings in the normalized TOML spelling used by the writer. This conversion loses their TOML kind. JSON also does not distinguish an integer from an integral float. A reverse conversion therefore need not restore the original TOML kinds. Comments and source number spellings are not preserved.

Both conversions visit array elements by index and object or table keys in the decoded key order →. They stop at the first unrepresentable child. The nonempty error identifies its path rooted at $ and its cause. Inputs remain unchanged and neither conversion performs I/O.