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

    Bytes.length

    Returns the number of bytes in this sequence.

    length: int
    Module
    std.bytes
    Receiver
    Bytes
    Minimum arity
    0
    Maximum arity
    0

    Declaration and parameters

    Link

    Availability

    Included by default: Pending

    Import std.bytes in language mode 5.21.

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

    Source evidence

    Receiver

    Bytes

    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

    Test whether a Bytes, Map, or Set value is empty by comparing its length property with zero. The comparison is true exactly when the collection has no bytes, entries, or elements.

    Bytes, Map, and Set do not expose an isEmpty member. Read the length property and use the ordinary equality operator.

    Related rule: Test collection emptiness with length

    A Bytes value is an immutable ordered sequence of octets. Each octet is an int from 0 through 255.

    Bytes.empty returns the empty sequence. Bytes.fromArray accepts an Array<int> and returns an independent snapshot in Ok.

    Bytes.fromArray returns Err with a string identifying the first element outside 0 through 255. It does not wrap, clamp, or return a partial sequence.

    Bytes.toArray returns a new Array<int> in byte order. Mutating that array or the original input array does not change an existing Bytes value.

    Bytes.concat returns the receiver bytes followed by the argument bytes. Either input may be empty and both inputs retain their contents.

    Bytes.get uses a zero-based byte index. It returns Some(byte) within the sequence and None() for every negative or past-end index.

    Bytes.length is the number of bytes and is read as a property. Compare it with zero to test emptiness.

    Receivers and supplied arguments evaluate once from left to right before the operation begins. These operations perform no I/O or text normalization.

    A correctly typed lookup or concatenation has no data-dependent Result failure. Allocation exhaustion is an operational failure and is not a decoded data error.

    Related rule: Construct and inspect immutable byte sequences

    Result

    Additional contracts are Pending.

    The declared result type is int.

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

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

    Read the number of bytes as a read-only int property. Compare it with zero to test emptiness.

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

    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

    Test collection emptiness with length

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

    Test collection emptiness with length

    Test whether a Bytes, Map, or Set value is empty by comparing its length property with zero. The comparison is true exactly when the collection has no bytes, entries, or elements.

    Bytes, Map, and Set do not expose an isEmpty member. Read the length property and use the ordinary equality operator.

    Why

    A collection already exposes its count through length. Comparing that value with zero expresses emptiness for every collection without another query name or a type-specific method.

    Examples Test empty and nonempty maps with lengthTest empty and nonempty sets with lengthTest empty and nonempty byte sequences with lengthReject Bytes.isEmptyReject Map.isEmptyReject Set.isEmpty

    Diagnostics TPZ5006

    Source evidence

    Test empty and nonempty maps with length

    Link

    run · running · Verification: not-run

    main.tpzTest empty and nonempty maps with lengthOpen in Playground
    1. import std.io
    3. let empty: Map<string, int> = map {}
    4. let filled = map { "one": 1 }
    5. io.writeLine("{empty.length == 0}:{filled.length == 0}")
    Expected outputexit 0
    true:false
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. true:false

    This exact example has not been executed.

    Source evidence

    Test empty and nonempty sets with length

    Link

    run · running · Verification: not-run

    main.tpzTest empty and nonempty sets with lengthOpen in Playground
    1. import std.io
    3. let empty: Set<int> = set {}
    4. let filled = set { 1 }
    5. io.writeLine("{empty.length == 0}:{filled.length == 0}")
    Expected outputexit 0
    true:false
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. true:false

    This exact example has not been executed.

    Source evidence

    Test empty and nonempty byte sequences with length

    Link

    run · running · Verification: not-run

    main.tpzTest empty and nonempty byte sequences with lengthOpen in Playground
    1. import std.bytes { Bytes }
    2. import std.test
    3. import std.io
    5. let empty = Bytes.empty()
    6. let filled = test.assertOk(Bytes.fromArray([1]))
    7. io.writeLine("{empty.length == 0}:{filled.length == 0}")
    Expected outputexit 0
    true:false
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. true:false

    This exact example has not been executed.

    Source evidence

    Reject Bytes.isEmpty

    Link

    reject · checking · Verification: not-run

    main.tpzReject Bytes.isEmptyOpen in Playground
    1. import std.bytes { Bytes }
    2. function inspect(value: Bytes) -> () {
    3. let result = value.isEmpty()
    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.

    • TPZ5006 stdlib-removed-member at main.tpz:3:22

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject Map.isEmpty

    Link

    reject · checking · Verification: not-run

    main.tpzReject Map.isEmptyOpen in Playground
    1. function inspect(value: Map<string, int>) -> () {
    2. let result = value.isEmpty()
    3. return ()
    4. }
    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.

    • TPZ5006 stdlib-removed-member at main.tpz:2:22

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject Set.isEmpty

    Link

    reject · checking · Verification: not-run

    main.tpzReject Set.isEmptyOpen in Playground
    1. function inspect(value: Set<int>) -> () {
    2. let result = value.isEmpty()
    3. return ()
    4. }
    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.

    • TPZ5006 stdlib-removed-member at main.tpz:2:22

    No stdout.

    This exact example has not been executed.

    Source evidence

    Diagnostics

    Link

    Unknown member or field

    Construct and inspect immutable byte sequences

    Link
    Ruletopaz.stdlib.contract.bytes-values.rule

    Construct and inspect immutable byte sequences

    A Bytes value is an immutable ordered sequence of octets. Each octet is an int from 0 through 255.

    Bytes.empty returns the empty sequence. Bytes.fromArray accepts an Array<int> and returns an independent snapshot in Ok.

    Bytes.fromArray returns Err with a string identifying the first element outside 0 through 255. It does not wrap, clamp, or return a partial sequence.

    Bytes.toArray returns a new Array<int> in byte order. Mutating that array or the original input array does not change an existing Bytes value.

    Bytes.concat returns the receiver bytes followed by the argument bytes. Either input may be empty and both inputs retain their contents.

    Bytes.get uses a zero-based byte index. It returns Some(byte) within the sequence and None() for every negative or past-end index.

    Bytes.length is the number of bytes and is read as a property. Compare it with zero to test emptiness.

    Receivers and supplied arguments evaluate once from left to right before the operation begins. These operations perform no I/O or text normalization.

    A correctly typed lookup or concatenation has no data-dependent Result failure. Allocation exhaustion is an operational failure and is not a decoded data error.

    Why

    Exact octets keep binary payloads independent of text encoding. Snapshot conversion prevents later array edits from silently changing a payload.

    Examples Preserve empty values and byte orderReject out-of-range array elementsRead optional bytes at both boundariesKeep array edits independent from bytesEvaluate the receiver before its argument

    Source evidence

    Preserve empty values and byte order

    Link

    run · running · Verification: not-run

    main.tpzPreserve empty values and byte orderOpen in Playground
    1. import std.bytes { Bytes }
    2. import std.io
    3. import std.test
    5. let empty = test.assertOk(Bytes.fromArray([]))
    6. let value = test.assertOk(Bytes.fromArray([0, 128, 255]))
    7. io.writeLine(Bytes.empty().toHex())
    8. io.writeLine(empty.concat(value).toHex())
    9. io.writeLine(value.concat(test.assertOk(Bytes.fromArray([1]))).toHex())
    Expected outputexit 0
    
0080ff
0080ff01
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    2. 0080ff
    3. 0080ff01

    This exact example has not been executed.

    Source evidence

    Reject out-of-range array elements

    Link

    run · running · Verification: not-run

    main.tpzReject out-of-range array elementsOpen in Playground
    1. import std.bytes { Bytes }
    2. import std.io
    4. for values in ([[0, -1, 255], [0, 256, 255]]) {
    5. match (Bytes.fromArray(values)) {
    6. case Err(_) => io.writeLine("invalid byte")
    7. case Ok(_) => io.writeLine("accepted")
    8. }
    9. }
    Expected outputexit 0
    invalid byte
invalid byte
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. invalid byte
    2. invalid byte

    This exact example has not been executed.

    Source evidence

    Read optional bytes at both boundaries

    Link

    run · running · Verification: not-run

    main.tpzRead optional bytes at both boundariesOpen in Playground
    1. import std.bytes { Bytes }
    2. import std.io
    3. import std.test
    5. let value = test.assertOk(Bytes.fromArray([0, 128, 255]))
    6. for index in ([-1, 0, 2, 3]) {
    7. match (value.get(index)) {
    8. case Some(byte) => io.writeLine("{byte}")
    9. case None() => io.writeLine("absent")
    10. }
    11. }
    Expected outputexit 0
    absent
0
255
absent
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. absent
    2. 0
    3. 255
    4. absent

    This exact example has not been executed.

    Source evidence

    Keep array edits independent from bytes

    Link

    run · running · Verification: not-run

    main.tpzKeep array edits independent from bytesOpen in Playground
    1. import std.bytes { Bytes }
    2. import std.io
    3. import std.test
    5. let mut input = [0, 255]
    6. let value = test.assertOk(Bytes.fromArray(input))
    7. let mut output = value.toArray()
    8. input[0] = 7
    9. output[1] = 8
    10. io.writeLine(value.toHex())
    11. io.writeLine("{input[0]},{output[1]}")
    Expected outputexit 0
    00ff
7,8
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 00ff
    2. 7,8

    This exact example has not been executed.

    Source evidence

    Evaluate the receiver before its argument

    Link

    run · running · Verification: not-run

    main.tpzEvaluate the receiver before its argumentOpen in Playground
    1. import std.bytes { Bytes }
    2. import std.io
    4. function receiver() -> Bytes {
    5. io.writeLine("receiver")
    6. return "a".encodeUtf8()
    7. }
    8. function argument() -> Bytes {
    9. io.writeLine("argument")
    10. return "b".encodeUtf8()
    11. }
    12. io.writeLine(receiver().concat(argument()).toHex())
    Expected outputexit 0
    receiver
argument
6162
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. receiver
    2. argument
    3. 6162

    This exact example has not been executed.

    Source evidence

    Menu

    Download