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

    Reads an optional byte at an index.

    get(index: int) -> Option<int>
    Module
    std.bytes
    Receiver
    Bytes
    Minimum arity
    1
    Maximum arity
    1

    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.

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

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

    Read a zero-based byte index as Some(byte). Negative and past-end indices return None().

    Resolved contracts

    Link

    Related entries

    Link

    std.bytes

    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