std.bytes

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.

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.

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.

Bytes.slice uses a start position and an exclusive end position measured in bytes.

Valid bounds satisfy 0 <= start <= end <= length. The result contains exactly the bytes from start through end minus one.

Equal endpoints produce empty Bytes, including endpoints at zero and at length. A full interval preserves every byte.

Negative bounds, inverted bounds, and endpoints beyond length produce TPZ4001 at runtime. Bounds are not clamped or interpreted from the end.

Slicing never changes the receiver. The receiver, start, and end expressions evaluate once in that order before the bounds are checked.

A byte interval may split a UTF-8 encoding. Bytes.slice preserves those selected octets and Bytes.decodeUtf8 reports invalid text when they form an incomplete sequence.

Bytes.toHex emits two lowercase ASCII hexadecimal digits per byte with the high nibble first. Empty Bytes produces an empty string.

Bytes.fromHex accepts an even number of digits drawn from 0 through 9 and a through f. Empty text returns Ok with empty Bytes.

Uppercase letters, prefixes, separators, whitespace, non-ASCII characters, and an odd digit count return Err with a string describing invalid hex input.

Decoding returns the entire byte sequence in Ok or an error with no decoded prefix. It never mutates an input value.

Encoding then decoding recovers the bytes exactly. Decoding then encoding preserves every accepted input spelling.

The input expression evaluates once. These conversions perform no I/O and do not apply Unicode normalization.

Bytes.toBase64 uses the RFC 4648 standard alphabet with plus and slash. Its output has no whitespace or line wrapping.

A final group containing one byte ends with two equals signs. A final group containing two bytes ends with one equals sign.

Bytes.fromBase64 accepts complete groups of four characters. Padding appears at the end of the final group and all unused bits are zero.

Missing or misplaced padding, nonzero unused bits, whitespace, non-ASCII characters, minus signs, and underscores return Err with a string.

Empty bytes encode as empty text and empty text decodes to Ok with empty Bytes. Invalid text never returns a partial byte sequence.

The input is evaluated once and is unchanged. Encoding then decoding recovers the input bytes exactly without any external effects.

Bytes.decodeUtf8 returns Ok with the exact Unicode scalar sequence encoded by valid UTF-8 bytes.

Empty Bytes returns Ok with an empty string. A leading UTF-8 encoding of U+FEFF remains in the returned string.

Overlong encodings, isolated continuation bytes, incomplete sequences, surrogate encodings, and values above U+10FFFF return Err with a string.

Decoding does not insert replacement characters, normalize scalars, alter newline sequences, or discard a byte order mark.

For a string, encodeUtf8 followed by decodeUtf8 returns the original string. Re-encoding any successfully decoded sequence recovers its original bytes.

The receiver evaluates once and remains unchanged. No text is exposed before the entire sequence has passed validation.

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.

ByteBuffer.get and ByteBuffer.set use zero-based byte indices from zero through length minus one. Get returns an int byte.

ByteBuffer.set replaces one byte. ByteBuffer.fill replaces length bytes beginning at start. Both require values from 0 through 255.

ByteBuffer.copy receives the source buffer, sourceStart, targetStart, and length in that order. The receiver is the destination.

Fill and copy use byte intervals → from each start to start plus length. Starts and lengths must be nonnegative. Every complete source and destination interval must fit its buffer without arithmetic overflow.

A zero length region at the end of a buffer is valid. A start beyond the end is invalid even when length is zero.

Copy observes the source interval before its first destination write. Copying within one buffer therefore supports overlap in either direction.

Set, fill, and copy return unit. They require a let mut root binding and update its destination value under collection value semantics →.

The receiver and supplied arguments evaluate once from left to right. Every range and byte check finishes before the first write.

An invalid index or region produces TPZ4001 at runtime. An invalid byte value produces TPZ5001 at runtime, including a fill of zero bytes.

A rejected operation performs no buffer writes. Effects performed while evaluating its receiver or arguments remain visible.

When several preconditions fail, the selected failing precondition is unspecified. The operation still completes every argument evaluation before validation and performs no writes.

Bytes.crc32 returns the unsigned CRC-32/ISO-HDLC value as an int from 0 through 4294967295.

CRC-32 uses width 32, polynomial 0x04c11db7, reflected input and output, initial value 0xffffffff, and final XOR 0xffffffff.

Bytes.sha256 and Bytes.sha512 implement FIPS 180-4 and return 32 and 64 digest bytes respectively.

Bytes.hmacSha256 uses its receiver as the key and its argument as the message. It returns the 32-byte HMAC-SHA-256 value from RFC 2104.

HMAC hashes a key longer than the 64-byte SHA-256 block before zero-padding it. Empty keys and messages are valid.

Empty input is valid for every checksum and digest. CRC-32 of empty input is zero.

These operations process stored bytes without decoding or normalization. Inputs remain unchanged and correctly typed calls have no data-dependent failure.

The receiver and any message argument evaluate once in that order. No external state, random input, or I/O affects the result.

Use toHex or toBase64 on a digest when a text encoding is required. Those encodings are separate from the digest bytes.

Bytes.deflateCompress returns Ok with one complete raw RFC 1951 DEFLATE stream. It adds no zlib or gzip header or checksum.

Bytes.deflateFixedCompress returns Ok with one final fixed Huffman block. Empty input is valid and the final unused bits are zero.

Fixed Huffman compression accepts at most 268435456 input bytes. Larger inputs return Err with a string before producing output.

Bytes.zlibFixedCompress applies the same fixed Huffman compression and input bound, with an RFC 1950 zlib header and Adler-32 trailer.

The zlib stream declares a 32768-byte window and no preset dictionary. Its header bytes are 0x78 and 0x01.

Bytes.deflateDecompress accepts raw streams containing stored, fixed Huffman, and dynamic Huffman blocks. It reconstructs the original bytes in Ok.

The decoder consumes one complete stream. Malformed or truncated blocks, invalid back-references, and complete trailing bytes return Err with a string.

Final unused padding bits are not decoded as data. A zlib or gzip wrapper is not a raw DEFLATE stream.

Bytes.deflateDecompress reverses either raw compressor for every supported input. Bytes.zlibFixedCompress requires a zlib decoder because its wrapper is part of the result.

Each receiver evaluates once and remains unchanged. The operations perform no I/O and errors expose no partially decoded Bytes.

Compression does not promise a particular size reduction. Except for the fixed block and wrapper requirements, encoded byte choices may change while preserving the stream format.

Bytes.gzipCompress returns Ok with one RFC 1952 gzip member containing the receiver bytes. Empty input is valid.

The compressor does not read a clock or derive a filename from its environment. The header timestamp is zero and optional name and comment fields are absent.

Bytes.gzipDecompress accepts one member with compression method DEFLATE, including valid timestamp, operating system, extra field, name, comment, and header CRC fields.

The decoder accepts stored, fixed Huffman, and dynamic Huffman DEFLATE blocks. It validates the member CRC-32 and uncompressed size modulo 4294967296.

Reserved header flags, malformed optional fields, invalid compressed data, checksum mismatches, and truncation return Err with a string.

A second member or other bytes after the member return Err. A Bytes value represents one complete compressed payload in this API.

Decoding a successfully compressed value recovers the original bytes. A decoder failure never exposes a prefix of the output.

The receiver evaluates once and remains unchanged. Compression and decompression perform no I/O and do not decode the payload as text.

Bytes.zstdCompress accepts an int level from 1 through 22. The default is 3 and other values return Err with a string.

The level is a compression effort hint. The API does not promise a size ratio, execution time, or different bytes for every pair of levels.

A successful call returns Ok with one RFC 8878 frame requiring no external dictionary. Empty input is valid.

Bytes.zstdDecompress accepts one standard frame containing raw, RLE, or compressed blocks, with valid frame parameters and an optional content checksum.

A frame requiring an unavailable dictionary, a malformed header or block, a size or checksum mismatch, and truncation return Err with a string.

Skippable frames, additional frames, and other trailing bytes return Err. The entire input must represent one data frame.

Decompression returns all uncompressed bytes in Ok or an error without a partial output. Compressing then decompressing preserves the input bytes.

The receiver and explicit level expression evaluate once in that order. The input remains unchanged and the operation performs no I/O.

Bytes.reedSolomon255223Protect accepts between 1 and 14614305 input bytes. Empty input and larger input return Err with a string.

Input bytes are partitioned into consecutive 223-byte data chunks. The final chunk is padded with zero bytes to 223 bytes.

Each output codeword contains its 223 data bytes followed by 32 parity bytes. Codewords are concatenated in input order.

The result contains 255 times the ceiling of input length divided by 223 bytes. At most 65535 codewords are produced.

Field arithmetic uses GF256 with primitive polynomial 0x11d and primitive element 2. Generator roots are the powers of that element from 0 through 31.

Treat the first data byte as the highest-degree coefficient. Parity is the 32-byte remainder after multiplying the data polynomial by x to the power 32.

The output contains no original length or additional framing. Callers must retain the input length to distinguish padding from original trailing zero bytes.

The operation generates parity bytes. It does not detect or correct corruption in existing codewords.

The receiver evaluates once and remains unchanged. Input bounds are checked before output allocation and failure exposes no codeword prefix.