Bytes
Immutable unsigned byte storage, strict explicit text encoding and endian conversions, byte pattern search, ownership and time and space complexity.
Bytes is an import free immutable contiguous sequence of unsigned eight bit values. It represents binary data explicitly and keeps arbitrary bytes separate from Unicode text.
Construction and ownership
let packet: Bytes = Bytes.from_values(values: List(0, 127, 255))
let text = Bytes.encode_utf8(text: "café")
print(packet.hex()) // 007fff
print(text.len()) // 5 encoded bytes
print(text.decode_utf8()) // caféBytes() creates an empty value. Bytes.from_values(values: List) checks every element: values must already be Int64 and lie between 0 and 255. Mixed scalar types, null, negative values, and values above 255 fail before output. The constructor copies values into native byte storage; later List mutation does not affect the Bytes.
Copies of a Bytes value share immutable storage in O(1) time and space. slice and concat allocate independent output buffers. The value has no mutation or resizing methods, so sharing cannot make one binding alter another. Each buffer is limited to 16 MiB; construction and composition check the result bound before allocation.
Explicit encoding and binary conversion
Bytes.encode_utf8(text: String) validates and encodes text without normalization. decode_utf8() validates all stored bytes and returns a String; malformed input fails rather than replacing characters. Encoded byte indices differ from the Unicode scalar indices used by String.
Bytes.from_hex(text: String) parses a complete even length ASCII hexadecimal representation. Uppercase and lowercase letters are accepted; whitespace, separators, and 0x prefixes are rejected. hex() produces lowercase hexadecimal text, exactly two digits per byte. These methods are an explicit textual representation, not an implicit binary to String conversion.
Bytes.from_i64(value: Int64, byte_order: String) writes exactly eight two's complement bytes. to_i64(byte_order: String) requires exactly eight bytes and interprets the same representation. The explicit order is "little" or "big"; no host endian default is inferred.
let encoded = Bytes.from_i64(value: -42, byte_order: "big")
print(encoded.hex())
print(encoded.to_i64(byte_order: "big")) // -42Methods and factories
| Method or factory | Result | Contract |
|---|---|---|
Bytes.from_values(values: List) | Bytes | Copy and validate Int64 byte values. |
Bytes.encode_utf8(text: String) | Bytes | Strictly encode Unicode text. |
Bytes.from_hex(text: String) | Bytes | Parse an even length hexadecimal representation. |
Bytes.try_from_hex(text: String) | Result<Bytes, String> | Return bytes or a recoverable hexadecimal validation error. |
Bytes.from_i64(value: Int64, byte_order: String) | Bytes | Encode exactly eight bytes in an explicit order. |
len() | Int64 | Number of bytes. |
is_empty() | Bool | Whether the buffer has no bytes. |
get(index: Int64) | Int64 | Return one unsigned byte as a value from 0 through 255. |
slice(start: Int64, end: Int64) | Bytes | Copy the half open byte interval [start, end). |
concat(other: Bytes) | Bytes | Return concatenated independent storage. |
find(needle: Bytes) | Int64 | First byte index, or −1; an empty needle returns 0. |
contains(needle: Bytes) | Bool | Test whether the exact byte pattern occurs. |
hex() | String | Lowercase hexadecimal representation. |
decode_utf8() | String | Strictly decode valid UTF-8, or fail. |
try_decode_utf8() | Result<String, String> | Return valid text or a recoverable decoding error. |
to_i64(byte_order: String) | Int64 | Interpret exactly eight bytes in the specified order. |
compare(other: Bytes) | Int64 | Lexicographic unsigned byte comparison: −1, 0, or 1. |
Indices must be nonnegative. get requires index < len(). slice requires 0 <= start <= end <= len() and accepts an empty interval. Comparison and equality examine byte contents, independently of storage sharing. type(value) reports Bytes; dtype(value) reports UInt8. UInt8 describes this storage and is not a separate accepted scalar or typed array element type in this release.
Errors and limits
A binary encoding, byte order, interval, or buffer limit violation produces a located runtime error R3402. Wrong static argument types or arities produce E1002. The corresponding documented try_ conversions represent expected validation failure as Result.err with a String payload rather than halting execution. A runtime failure retains the normal program or persistent session error contract.
Time and space complexity
Let n be receiver bytes, m pattern or other bytes, and k copied slice bytes. Persistent storage is O(n); shared copies add O(1) metadata.
| Operation | Time | Additional space |
|---|---|---|
Empty construction, shared copy, len, is_empty, get | O(1) | O(1). |
from_values, encode_utf8, from_hex, decode_utf8, hex | O(n) | O(n) output; input validation included. |
slice | O(k) | O(k) output. |
concat | O(n + m) | O(n + m) output. |
find, contains | O(n + m) | O(m) search prefix metadata. |
Equality and compare | O(min(n, m)) worst case after length checks | O(1). |
from_i64, to_i64 | O(1) | O(1), exactly eight bytes. |
List conversion validates the source directly and allocates only the native byte output, without an intermediate Int64 buffer. Ordinary String argument evaluation can copy its input bytes. Hex output contains 2n String bytes and must fit the 16 MiB String limit: hex() therefore rejects input above 8 MiB. The shared execution heap also counts directly retained Bytes/String payload lengths against its 16 MiB logical payload budget, conservatively for each retained slot even when Bytes storage is shared. These bounds are not an overall process memory quota.