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.json.stringify

    Serializes a value as JSON text.

    stringify<T>(value: T) -> Result<string, string>
    Module
    std.json
    Receiver
    Not applicable
    Minimum arity
    1
    Maximum arity
    1

    Declaration and parameters

    Link

    Availability

    Included by default: Pending

    Import std.json in language mode 5.21.

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

    Source evidence

    Receiver

    Not applicable

    Parameter constraints

    Additional contracts are Pending.

    stringify requires the JSON conformance of its input type. It calls JSON.encode once and writes the returned JSON tree. A type without that conformance is rejected during checking with TPZ5533. The protocol representation rules define records, enums, arrays, maps, options, results and custom codecs.

    Successful output contains one compact JSON value with no leading whitespace or terminal newline. Object names follow the decoded key order. Arrays retain their element order. Map insertion order and record declaration order do not choose serialization order.

    The writer escapes quotation marks and backslashes. It uses the short escapes for LF, CR and tab. Other controls below U+0020 use four digit lowercase Unicode escapes. Other scalar values are emitted unchanged. It does not escape a slash or normalize Unicode.

    An existing JSONValue retains every accepted number lexeme. An int uses decimal digits and an optional minus. Float encoding follows JSON numeric conversion, including its shortest binary64 roundtrip spelling and negative zero. NaN and infinities return Err.

    The depth and active value cycle rules of JSON conversion apply. A depth above 128 or a value cycle returns an error beginning JSON_LIMIT. Other value failures return the selected codec error. Built in conversion errors identify the first failing child with a path rooted at $.

    The input expression is evaluated before conversion. Built in conversions visit arrays in index order and objects in sorted key order. A custom encoder retains its ordinary evaluation and side effects. An encoder error prevents writing. This function returns text and performs no filesystem or stream write.

    Related rule: Serialize JSON in a deterministic order

    Result

    Additional contracts are Pending.

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

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

    Encode through the JSON protocol and return compact deterministic JSON text.

    Related entries

    Link

    std.json

    Serialize JSON in a deterministic order

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

    Serialize JSON in a deterministic order

    stringify requires the JSON conformance of its input type. It calls JSON.encode once and writes the returned JSON tree. A type without that conformance is rejected during checking with TPZ5533. The protocol representation rules define records, enums, arrays, maps, options, results and custom codecs.

    Successful output contains one compact JSON value with no leading whitespace or terminal newline. Object names follow the decoded key order. Arrays retain their element order. Map insertion order and record declaration order do not choose serialization order.

    The writer escapes quotation marks and backslashes. It uses the short escapes for LF, CR and tab. Other controls below U+0020 use four digit lowercase Unicode escapes. Other scalar values are emitted unchanged. It does not escape a slash or normalize Unicode.

    An existing JSONValue retains every accepted number lexeme. An int uses decimal digits and an optional minus. Float encoding follows JSON numeric conversion, including its shortest binary64 roundtrip spelling and negative zero. NaN and infinities return Err.

    The depth and active value cycle rules of JSON conversion apply. A depth above 128 or a value cycle returns an error beginning JSON_LIMIT. Other value failures return the selected codec error. Built in conversion errors identify the first failing child with a path rooted at $.

    The input expression is evaluated before conversion. Built in conversions visit arrays in index order and objects in sorted key order. A custom encoder retains its ordinary evaluation and side effects. An encoder error prevents writing. This function returns text and performs no filesystem or stream write.

    Why

    Stable JSON bytes support fixtures and reproducible document inputs. The existing JSON conformance supplies one conversion path, while a Result distinguishes invalid values from successful text.

    Examples Write sorted objects and preserve a parsed number lexemeWrite finite float values and reject a nonfinite value

    Source evidence

    Write sorted objects and preserve a parsed number lexeme

    Link

    run · running · Verification: not-run

    main.tpzWrite sorted objects and preserve a parsed number lexemeOpen in Playground
    1. import std.json
    2. import std.test
    3. import std.io
    4. io.writeLine(test.assertOk(json.stringify(map { "z": 1, "a": 2 })))
    5. io.writeLine(test.assertOk(json.stringify(["a,b", "x\"y", "\n", "é"])))
    6. let number = test.assertOk(json.parse("1.2300e+03"))
    7. io.writeLine(test.assertOk(json.stringify(number)))
    8. let empty: Array<int> = []
    9. io.writeLine(test.assertOk(json.stringify(empty)))
    Expected outputexit 0
    {"a":2,"z":1}
["a,b","x\"y","\n","é"]
1.2300e+03
[]
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. {"a":2,"z":1}
    2. ["a,b","x\"y","\n","é"]
    3. 1.2300e+03
    4. []

    This exact example has not been executed.

    Source evidence

    Write finite float values and reject a nonfinite value

    Link

    run · running · Verification: not-run

    main.tpzWrite finite float values and reject a nonfinite valueOpen in Playground
    1. import std.json
    2. import std.io
    3. for value in ([1.5, -0.0]) {
    4. match (json.stringify(value)) {
    5. case Ok(text) => io.writeLine(text)
    6. case Err(_) => io.writeLine("rejected")
    7. }
    8. }
    9. match (json.stringify(0.0 / 0.0)) {
    10. case Ok(_) => io.writeLine("accepted")
    11. case Err(_) => io.writeLine("nonfinite rejected")
    12. }
    Expected outputexit 0
    1.5
-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. 1.5
    2. -0
    3. nonfinite rejected

    This exact example has not been executed.

    Source evidence

    Menu

    Download