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.length

    Returns an optional length for this JSON value.

    length: Option<int>
    Module
    std.json
    Receiver
    JSONValue
    Minimum arity
    0
    Maximum arity
    0

    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.

    Bytes.length and ByteBuffer.length are read-only int properties that report the number of bytes.

    JSONValue.length is an Option<int> property. Arrays and objects return Some(count) for their element or member count. Other JSON kinds return None().

    JSONValue.keys and JSONValue.values are properties returning Option<Array<string>> and Option<Array<JSONValue>>. Objects return Some(keys) or Some(values). Other JSON kinds return None().

    Read these properties without parentheses, as with Array.length, Map.length, Map.keys, Map.values, and Set.length. Calling a property value is rejected as a non-callable value.

    Related rule: Read collection sizes, keys, and values as properties

    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<int>.

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

    Select this field from a value of its named type without call parentheses.

    Read the optional number of array elements or object members through a property.

    Why

    Link

    Collection observations use the same property syntax as Array, Map, and Set. Parentheses identify calls rather than stored or derived values.

    Related entries

    Link

    std.json

    Read collection sizes, keys, and values as properties

    Link
    Ruletopaz.stdlib.contract.collection-properties.rule

    Read collection sizes, keys, and values as properties

    Bytes.length and ByteBuffer.length are read-only int properties that report the number of bytes.

    JSONValue.length is an Option<int> property. Arrays and objects return Some(count) for their element or member count. Other JSON kinds return None().

    JSONValue.keys and JSONValue.values are properties returning Option<Array<string>> and Option<Array<JSONValue>>. Objects return Some(keys) or Some(values). Other JSON kinds return None().

    Read these properties without parentheses, as with Array.length, Map.length, Map.keys, Map.values, and Set.length. Calling a property value is rejected as a non-callable value.

    Why

    The same collection observation should use the same syntax across core collections and library values. Keeping JSONValue results optional preserves its distinction between collections and scalar values.

    Examples Read the same properties on core collectionsRead a byte sequence sizeRead a byte buffer sizeRead JSON sizes and preserve optional resultsRead JSON object keysRead JSON object valuesReject calling Bytes.lengthReject calling ByteBuffer.lengthReject calling JSONValue.lengthReject calling JSONValue.keysReject calling JSONValue.values

    Diagnostics TPZ5005

    Source evidence

    Read the same properties on core collections

    Link

    run · running · Verification: not-run

    main.tpzRead the same properties on core collectionsOpen in Playground
    1. import std.io
    3. let array = [2, 3]
    4. let entries = map { "name": "Topaz" }
    5. let values = set { 2, 3 }
    6. io.writeLine("{array.length}:{entries.length}:{values.length}")
    7. io.writeLine(entries.keys[0])
    8. io.writeLine(entries.values[0])
    Expected outputexit 0
    2:1:2
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. 2:1:2
    2. name
    3. Topaz

    This exact example has not been executed.

    Source evidence

    Read a byte sequence size

    Link

    run · running · Verification: not-run

    main.tpzRead a byte sequence sizeOpen in Playground
    1. import std.bytes { Bytes }
    2. import std.io
    4. let bytes = Bytes.empty()
    5. let size: int = bytes.length
    6. io.writeLine("{size}")
    Expected outputexit 0
    0
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 0

    This exact example has not been executed.

    Source evidence

    Read a byte buffer size

    Link

    run · running · Verification: not-run

    main.tpzRead a byte buffer sizeOpen in Playground
    1. import std.bytes { ByteBuffer }
    2. import std.io
    4. let buffer = ByteBuffer.allocate(3)
    5. let size: int = buffer.length
    6. io.writeLine("{size}")
    Expected outputexit 0
    3
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 3

    This exact example has not been executed.

    Source evidence

    Read JSON sizes and preserve optional results

    Link

    run · running · Verification: not-run

    main.tpzRead JSON sizes and preserve optional resultsOpen in Playground
    1. import std.json
    2. import std.test
    3. import std.io
    5. let array = test.assertOk(json.parse("[1,2]"))
    6. let object = test.assertOk(json.parse("\{\"name\":\"Topaz\"\}"))
    7. let scalar = test.assertOk(json.parse("42"))
    8. let arraySize: Option<int> = array.length
    9. let objectSize: Option<int> = object.length
    10. let scalarSize: Option<int> = scalar.length
    11. test.assertEq(test.assertSome(arraySize), 2)
    12. test.assertEq(test.assertSome(objectSize), 1)
    13. test.assertNone(scalarSize)
    14. io.writeLine("JSON sizes read")
    Expected outputexit 0
    JSON sizes read
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. JSON sizes read

    This exact example has not been executed.

    Source evidence

    Read JSON object keys

    Link

    run · running · Verification: not-run

    main.tpzRead JSON object keysOpen in Playground
    1. import std.json
    2. import std.test
    3. import std.io
    5. let object = test.assertOk(json.parse("\{\"name\":\"Topaz\"\}"))
    6. let array = test.assertOk(json.parse("[]"))
    7. let scalar = test.assertOk(json.parse("42"))
    8. let names: Option<Array<string>> = object.keys
    9. test.assertEq(test.assertSome(names)[0], "name")
    10. test.assertNone(array.keys)
    11. test.assertNone(scalar.keys)
    12. io.writeLine("JSON keys read")
    Expected outputexit 0
    JSON keys read
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. JSON keys read

    This exact example has not been executed.

    Source evidence

    Read JSON object values

    Link

    run · running · Verification: not-run

    main.tpzRead JSON object valuesOpen in Playground
    1. import std.json
    2. import std.test
    3. import std.io
    5. let object = test.assertOk(json.parse("\{\"name\":\"Topaz\"\}"))
    6. let array = test.assertOk(json.parse("[]"))
    7. let scalar = test.assertOk(json.parse("42"))
    8. let values = test.assertSome(object.values)
    9. test.assertEq(test.assertSome(values[0].asString()), "Topaz")
    10. test.assertNone(array.values)
    11. test.assertNone(scalar.values)
    12. io.writeLine("JSON values read")
    Expected outputexit 0
    JSON values read
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. JSON values read

    This exact example has not been executed.

    Source evidence

    Reject calling Bytes.length

    Link

    reject · checking · Verification: not-run

    main.tpzReject calling Bytes.lengthOpen in Playground
    1. import std.bytes { Bytes }
    2. function inspect(value: Bytes) -> () {
    3. let result = value.length()
    4. return ()
    5. }
    Expected outputNonzero exit
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5005 stdlib-property-not-callable at main.tpz:3:22

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject calling ByteBuffer.length

    Link

    reject · checking · Verification: not-run

    main.tpzReject calling ByteBuffer.lengthOpen in Playground
    1. import std.bytes { ByteBuffer }
    2. function inspect(value: ByteBuffer) -> () {
    3. let result = value.length()
    4. return ()
    5. }
    Expected outputNonzero exit
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5005 stdlib-property-not-callable at main.tpz:3:22

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject calling JSONValue.length

    Link

    reject · checking · Verification: not-run

    main.tpzReject calling JSONValue.lengthOpen in Playground
    1. import std.json { JSONValue }
    2. function inspect(value: JSONValue) -> () {
    3. let result = value.length()
    4. return ()
    5. }
    Expected outputNonzero exit
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5005 stdlib-property-not-callable at main.tpz:3:22

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject calling JSONValue.keys

    Link

    reject · checking · Verification: not-run

    main.tpzReject calling JSONValue.keysOpen in Playground
    1. import std.json { JSONValue }
    2. function inspect(value: JSONValue) -> () {
    3. let result = value.keys()
    4. return ()
    5. }
    Expected outputNonzero exit
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5005 stdlib-property-not-callable at main.tpz:3:22

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject calling JSONValue.values

    Link

    reject · checking · Verification: not-run

    main.tpzReject calling JSONValue.valuesOpen in Playground
    1. import std.json { JSONValue }
    2. function inspect(value: JSONValue) -> () {
    3. let result = value.values()
    4. return ()
    5. }
    Expected outputNonzero exit
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5005 stdlib-property-not-callable at main.tpz:3:22

    No stdout.

    This exact example has not been executed.

    Source evidence

    Diagnostics

    Link

    Value is not callable

    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