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

    JSONValue.at

    Looks up a JSON value by array index.

    at(index: int) -> Option<JSONValue>
    Module
    std.json
    Receiver
    JSONValue
    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

    JSONValue

    Parameter constraints

    Additional contracts are Pending.

    JSONValue is an immutable JSON tree with the six JSON kinds. Reading a member preserves the tree.

    asBool and asString return Some for the matching kind and None() for every other kind. False and empty text are present values. Neither function parses text or converts a number.

    numberText returns the exact accepted number lexeme for a number and None() for another kind. It preserves a negative zero, exponent spelling and fractional trailing zeroes.

    asInt returns Some for a number spelled as an optional minus and decimal integer digits within the signed 64 bit range. Negative zero becomes zero. A decimal point, exponent, overflow or different kind returns None() without rounding.

    asArray returns the elements of an array in source order. Another kind returns None(). The returned array is a separate collection. Changing that collection does not change the JSON tree.

    at uses a zero based array index. A negative index, an index at or beyond the array length, or a receiver of another kind returns None(). get uses an exact decoded object key and returns None() for an absent key or another receiver kind. A present null child is Some containing JSON null.

    length is a property containing the array element count or object member count. Scalar kinds yield None(). keys and values are object properties. They contain arrays in ascending Unicode scalar order of decoded keys, with corresponding positions. Array and scalar receivers yield None() for both properties.

    The receiver and supplied arguments are evaluated once in ordinary call order. Inspection performs no I/O and invokes no user conversion. Incorrect argument types follow ordinary checking diagnostics rather than becoming absent values.

    Related rule: Project JSON values without coercion

    Result

    Additional contracts are Pending.

    The declared result type is Option<JSONValue>.

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

    Return the optional array child at a zero based index.

    Related entries

    Link

    std.json

    Project JSON values without coercion

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

    Project JSON values without coercion

    JSONValue is an immutable JSON tree with the six JSON kinds. Reading a member preserves the tree.

    asBool and asString return Some for the matching kind and None() for every other kind. False and empty text are present values. Neither function parses text or converts a number.

    numberText returns the exact accepted number lexeme for a number and None() for another kind. It preserves a negative zero, exponent spelling and fractional trailing zeroes.

    asInt returns Some for a number spelled as an optional minus and decimal integer digits within the signed 64 bit range. Negative zero becomes zero. A decimal point, exponent, overflow or different kind returns None() without rounding.

    asArray returns the elements of an array in source order. Another kind returns None(). The returned array is a separate collection. Changing that collection does not change the JSON tree.

    at uses a zero based array index. A negative index, an index at or beyond the array length, or a receiver of another kind returns None(). get uses an exact decoded object key and returns None() for an absent key or another receiver kind. A present null child is Some containing JSON null.

    length is a property containing the array element count or object member count. Scalar kinds yield None(). keys and values are object properties. They contain arrays in ascending Unicode scalar order of decoded keys, with corresponding positions. Array and scalar receivers yield None() for both properties.

    The receiver and supplied arguments are evaluated once in ordinary call order. Inspection performs no I/O and invokes no user conversion. Incorrect argument types follow ordinary checking diagnostics rather than becoming absent values.

    Why

    Optional projection keeps a missing child distinct from a stored null. Number text preserves the original representation, while the integer projection has an explicit spelling and range. Sorted key and value positions support deterministic traversal.

    Examples Inspect present values and missing childrenKeep integer projection within the declared spelling and rangeRead matching keys and values in scalar order

    Source evidence

    Inspect present values and missing children

    Link

    run · running · Verification: not-run

    main.tpzInspect present values and missing childrenOpen in Playground
    1. import std.json
    2. import std.test
    3. import std.io
    4. let value = test.assertOk(json.parse("[false,\"\",null,7]"))
    5. let items = test.assertSome(value.asArray())
    6. test.assertEq(test.assertSome(items[0].asBool()), false)
    7. test.assertEq(test.assertSome(items[1].asString()), "")
    8. test.assertEq(items[2].kind(), "null")
    9. test.assertEq(test.assertSome(items[3].asInt()), 7)
    10. test.assertNone(value.at(-1))
    11. test.assertNone(value.at(4))
    12. test.assertNone(value.get("0"))
    13. test.assertNone(items[0].asString())
    14. test.assertNone(items[1].numberText())
    15. test.assertNone(items[2].asArray())
    16. let object = test.assertOk(json.parse("\{\"present\":null\}"))
    17. test.assertEq(test.assertSome(object.get("present")).kind(), "null")
    18. test.assertNone(object.get("missing"))
    19. test.assertNone(object.at(0))
    20. io.writeLine("present values remain distinct from missing children")
    Expected outputexit 0
    present values remain distinct from missing children
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. present values remain distinct from missing children

    This exact example has not been executed.

    Source evidence

    Keep integer projection within the declared spelling and range

    Link

    run · running · Verification: not-run

    main.tpzKeep integer projection within the declared spelling and rangeOpen in Playground
    1. import std.json
    2. import std.test
    3. import std.io
    4. for text in (["-9223372036854775808", "9223372036854775807", "9223372036854775808", "-0", "1.0", "1e0", "1.5"]) {
    5. let value = test.assertOk(json.parse(text))
    6. match (value.asInt()) {
    7. case Some(number) => io.writeLine("{text} = {number}")
    8. case None() => io.writeLine("{text} = none")
    9. }
    10. }
    Expected outputexit 0
    -9223372036854775808 = -9223372036854775808
9223372036854775807 = 9223372036854775807
9223372036854775808 = none
-0 = 0
1.0 = none
1e0 = none
1.5 = none
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. -9223372036854775808 = -9223372036854775808
    2. 9223372036854775807 = 9223372036854775807
    3. 9223372036854775808 = none
    4. -0 = 0
    5. 1.0 = none
    6. 1e0 = none
    7. 1.5 = none

    This exact example has not been executed.

    Source evidence

    Read matching keys and values in scalar order

    Link

    run · running · Verification: not-run

    main.tpzRead matching keys and values in scalar orderOpen in Playground
    1. import std.json
    2. import std.test
    3. import std.io
    4. let object = test.assertOk(json.parse("\{\"z\":1,\"a\":null\}"))
    5. let names = test.assertSome(object.keys)
    6. let values = test.assertSome(object.values)
    7. test.assertEq(test.assertSome(object.length), 2)
    8. io.writeLine("{names[0]} = {values[0].kind()}")
    9. io.writeLine("{names[1]} = {test.assertSome(values[1].asInt())}")
    10. let array = test.assertOk(json.parse("[]"))
    11. test.assertEq(test.assertSome(array.length), 0)
    12. test.assertNone(array.keys)
    13. test.assertNone(array.values)
    14. let scalar = test.assertOk(json.parse("\"text\""))
    15. test.assertNone(scalar.length)
    Expected outputexit 0
    a = null
z = 1
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. a = null
    2. z = 1

    This exact example has not been executed.

    Source evidence

    Menu

    Download