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

    Creates a mutable byte buffer with the supplied length and initial value.

    allocate(length: int, value: int = 0) -> ByteBuffer
    Module
    std.bytes
    Receiver
    Not applicable
    Minimum arity
    1
    Maximum arity
    2

    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

    Not applicable

    Parameter constraints

    Additional contracts are Pending.

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

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

    Allocate a fixed buffer with a nonnegative byte count and a byte value from 0 through 255. The initial value defaults to zero.

    Resolved contracts

    Link

    Related entries

    Link

    std.bytes

    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