Skip to content
Topaz6.0 · Before release
Download

Search documentation

Specification 6.0 · Not released · Tested product 5.21.3

Use arrow keys to choose a result. Press Enter to open.

Type an API name, diagnostic number, rule, or project topic.

    Library · std.toml

    TOMLValue.toJson

    Converts this TOML value to a JSON value.

    toJson() -> Result<JSONValue, string>
    Module
    std.toml
    Receiver
    TOMLValue
    Minimum arity
    0
    Maximum arity
    0

    Declaration and parameters

    Link

    Availability

    Included by default: Pending

    Import std.toml in language mode 5.21.

    The current compiler selects std/toml.tpz for this language mode. Availability in other released editions and inclusion in each installed distribution are Pending.

    Source evidence

    Receiver

    TOMLValue

    Parameter constraints

    Additional contracts are Pending.

    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.

    Related rule: Convert TOML and JSON with explicit failures

    Result

    Additional contracts are Pending.

    The declared result type is Result<JSONValue, string>.

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

    Convert TOML recursively and return an error for a nonfinite number.

    Related entries

    Link

    std.toml

    Convert TOML and JSON with explicit failures

    Link
    Ruletopaz.stdlib.contract.toml-json.rule

    Convert TOML and JSON with explicit failures

    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.

    Why

    A format conversion must expose values that its destination cannot represent. A Result keeps nonfinite failure explicit and avoids inventing a second conversion function or silently changing a numeric value into another kind.

    Examples Reject null and out of range integer conversionIdentify the first unrepresentable childConvert a TOML table through a recoverable JSON resultReturn an error for a TOML infinity during JSON conversion

    Source evidence

    Reject null and out of range integer conversion

    Link

    run · running · Verification: not-run

    main.tpzReject null and out of range integer conversionOpen in Playground
    1. import std.json
    2. import std.toml
    3. import std.test
    4. import std.io
    5. for text in (["null", "9223372036854775808", "1e9999"]) {
    6. let value = test.assertOk(json.parse(text))
    7. match (toml.fromJson(value)) {
    8. case Ok(_) => io.writeLine("accepted")
    9. case Err(_) => io.writeLine("unrepresentable")
    10. }
    11. }
    Expected outputexit 0
    unrepresentable
unrepresentable
unrepresentable
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. unrepresentable
    2. unrepresentable
    3. unrepresentable

    This exact example has not been executed.

    Source evidence

    Identify the first unrepresentable child

    Link

    run · running · Verification: not-run

    main.tpzIdentify the first unrepresentable childOpen in Playground
    1. import std.json
    2. import std.toml
    3. import std.test
    4. import std.io
    5. let value = test.assertOk(json.parse("\{\"x\":[null]\}"))
    6. let error = test.assertErr(toml.fromJson(value))
    7. test.assertContains(error, "$.x[0]")
    8. io.writeLine("child located")
    Expected outputexit 0
    child located
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. child located

    This exact example has not been executed.

    Source evidence

    Convert a TOML table through a recoverable JSON result

    Link

    run · running · Verification: not-run

    main.tpzConvert a TOML table through a recoverable JSON resultOpen in Playground
    1. import std.json
    2. import std.toml
    3. import std.test
    4. import std.io
    5. let value = test.assertOk(toml.parse("name = \"Topaz\"\ncount = 6\n"))
    6. let tree = test.assertOk(value.toJson())
    7. io.writeLine(test.assertOk(json.stringify(tree)))
    8. let restored = test.assertOk(toml.fromJson(tree))
    9. io.writeLine(test.assertOk(toml.stringify(restored)))
    Expected outputexit 0
    {"count":6,"name":"Topaz"}
count = 6
name = "Topaz"
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. {"count":6,"name":"Topaz"}
    2. count = 6
    3. name = "Topaz"

    This exact example has not been executed.

    Source evidence

    Return an error for a TOML infinity during JSON conversion

    Link

    run · running · Verification: not-run

    main.tpzReturn an error for a TOML infinity during JSON conversionOpen in Playground
    1. import std.toml
    2. import std.test
    3. import std.io
    4. let value = test.assertOk(toml.parse("value = inf\n"))
    5. match (value.toJson()) {
    6. case Ok(_) => io.writeLine("accepted")
    7. case Err(_) => io.writeLine("nonfinite rejected")
    8. }
    Expected outputexit 0
    nonfinite rejected
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. nonfinite rejected

    This exact example has not been executed.

    Source evidence

    Menu

    Download