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

    ByteBuffer.length

    Returns the number of bytes in this buffer.

    length: int
    Module
    std.bytes
    Receiver
    ByteBuffer
    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

    ByteBuffer

    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

    ByteBuffer.allocate accepts a nonnegative int length and an int initial value from 0 through 255. The initial value defaults to zero.

    The new buffer has exactly that many copies of the initial byte. Zero length is valid and still requires a valid initial byte.

    A negative length produces TPZ4001 at runtime. An invalid initial byte or an allocation that cannot be satisfied produces TPZ5001 at runtime.

    ByteBuffer.fromBytes converts an immutable Bytes value into a mutable ByteBuffer value containing the same bytes.

    ByteBuffer.toBytes converts the current buffer contents into an immutable Bytes value.

    ByteBuffer.length is a read-only byte count property. Buffer operations never change its length.

    Assignment, argument passing, return, capture, and aggregate storage follow collection value semantics.

    Supplied expressions evaluate once from left to right before allocation or conversion. These operations have no I/O effects.

    Related rule: Allocate buffers and convert byte values

    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 fixed number of buffer bytes as a read-only int property. Buffer writes preserve this count.

    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

    Allocate buffers and convert byte values

    Link
    Ruletopaz.stdlib.contract.byte-buffer-storage.rule

    Allocate buffers and convert byte values

    ByteBuffer.allocate accepts a nonnegative int length and an int initial value from 0 through 255. The initial value defaults to zero.

    The new buffer has exactly that many copies of the initial byte. Zero length is valid and still requires a valid initial byte.

    A negative length produces TPZ4001 at runtime. An invalid initial byte or an allocation that cannot be satisfied produces TPZ5001 at runtime.

    ByteBuffer.fromBytes converts an immutable Bytes value into a mutable ByteBuffer value containing the same bytes.

    ByteBuffer.toBytes converts the current buffer contents into an immutable Bytes value.

    ByteBuffer.length is a read-only byte count property. Buffer operations never change its length.

    Assignment, argument passing, return, capture, and aggregate storage follow collection value semantics.

    Supplied expressions evaluate once from left to right before allocation or conversion. These operations have no I/O effects.

    Why

    A fixed length gives binary algorithms stable byte positions. Explicit conversion distinguishes mutable construction from immutable byte data.

    Examples Allocate zero-filled and initialized buffersKeep the original buffer and converted bytes unchangedReject a negative buffer lengthValidate the initial byte of an empty bufferValidate the initial byte of an empty buffer

    Diagnostics TPZ4001TPZ5001

    Source evidence

    Allocate zero-filled and initialized buffers

    Link

    run · running · Verification: not-run

    main.tpzAllocate zero-filled and initialized buffersOpen in Playground
    1. import std.bytes { ByteBuffer }
    2. import std.io
    4. io.writeLine(ByteBuffer.allocate(0).toBytes().toHex())
    5. io.writeLine(ByteBuffer.allocate(3).toBytes().toHex())
    6. io.writeLine(ByteBuffer.allocate(2, 255).toBytes().toHex())
    Expected outputexit 0
    
000000
ffff
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    2. 000000
    3. ffff

    This exact example has not been executed.

    Source evidence

    Keep the original buffer and converted bytes unchanged

    Link

    run · running · Verification: not-run

    main.tpzKeep the original buffer and converted bytes unchangedOpen in Playground
    1. import std.bytes { ByteBuffer }
    2. import std.io
    4. let source = "ab".encodeUtf8()
    5. let buffer = ByteBuffer.fromBytes(source)
    6. let independent = ByteBuffer.fromBytes(source)
    7. let before = buffer.toBytes()
    8. let mut alias = buffer
    9. alias.set(0, 99)
    10. io.writeLine(source.toHex())
    11. io.writeLine(before.toHex())
    12. io.writeLine(independent.toBytes().toHex())
    13. io.writeLine(buffer.toBytes().toHex())
    Expected outputexit 0
    6162
6162
6162
6162
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 6162
    2. 6162
    3. 6162
    4. 6162

    This exact example has not been executed.

    Source evidence

    Reject a negative buffer length

    Link

    run · running · Verification: not-run

    main.tpzReject a negative buffer lengthOpen in Playground
    1. import std.bytes { ByteBuffer }
    2. ByteBuffer.allocate(-1)
    Expected outputNonzero exit
    No stdout.
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Rejection during run. Nonzero exit.

    • TPZ4001 byte-buffer-negative-bound at main.tpz:2:1

    No stdout.

    This exact example has not been executed.

    Source evidence

    Validate the initial byte of an empty buffer

    Link

    run · running · Verification: not-run

    main.tpzValidate the initial byte of an empty bufferOpen in Playground
    1. import std.bytes { ByteBuffer }
    2. import std.io
    3. ByteBuffer.allocate(0, -1)
    4. io.writeLine("after")
    Expected outputNonzero exit
    No stdout.
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Rejection during run. Nonzero exit.

    • TPZ5001 byte-buffer-byte-value at main.tpz:3:1

    No stdout.

    This exact example has not been executed.

    Source evidence

    Validate the initial byte of an empty buffer

    Link

    run · running · Verification: not-run

    main.tpzValidate the initial byte of an empty bufferOpen in Playground
    1. import std.bytes { ByteBuffer }
    2. import std.io
    3. ByteBuffer.allocate(0, 256)
    4. io.writeLine("after")
    Expected outputNonzero exit
    No stdout.
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Rejection during run. Nonzero exit.

    • TPZ5001 byte-buffer-byte-value at main.tpz:3:1

    No stdout.

    This exact example has not been executed.

    Source evidence

    Diagnostics

    Link

    Index out of bounds

    Runtime value guard

    Menu

    Download