Library / Strings / Bytes / ByteBuffer
ByteBuffer
Immutable opaque binary data container.
Constructors 4
INIT()CONSTRUCTORS / CLEANUP
INIT(REFERENCE binary[] origin)
Construct from a pre-built byte array, COPYING it. Every internal
transformation (subBuffer, concat, clone) constructs its result this
way: build a fresh binary[], hand it to a new ByteBuffer.
REFERENCE, not owning: the class allocates its own storage rather
than adopting the caller's. This was the last owning constructor in the
text/binary family and the only one that adopted caller memory — every
other kernel class allocates its own, so the outlier moved rather than
the pattern. It costs one copy per construction, and buys a uniform rule:
handing an array to a constructor never takes it away from you.
INIT(binary[] origin, int64 length)
Similar to String, we have an owning binary[] for performance
length IS REDUNDANT AND MUST NOT BE REMOVED.
INIT(REFERENCE ByteBuffer other)
Copy-construct from another ByteBuffer. One allocation, one bulk copy — the element loop this replaced wrote at the high-water mark, so the storage reallocated as it filled.
Methods 24
METHOD clone() RETURNS ByteBufferreads
CLONE — hand-written. Hands the storage straight to the copying constructor, which reserves once and bulk-copies.
It used to build an intermediate binary[] byte by byte and hand THAT
over, which cost two full copies and an extra allocation: once into the
intermediate, once out of it. That shape made sense when the constructor
took the array by ownership and adopted the array; under REFERENCE the intermediate is
pure waste, because the constructor was going to copy anyway.
METHOD isEmpty() RETURNS booleanreads
INSPECTION
METHOD size() RETURNS int64reads
METHOD length() RETURNS int64reads
Byte count — the same number size() returns. On the byte axis the two
coincide, because a byte IS the storage unit; on the text axis they
differ (String.length() counts code points, String.size() counts
UTF-8 bytes). Both names exist on all six text/binary classes so a
caller never has to remember which axis they are holding.
METHOD __op_index__(int64 i) RETURNS binaryreads
Byte at index i — buf[i] yields the raw binary. THE element
accessor: a pipe-XOR at() stood beside it until Phase 3, which left
the byte axis with two ways to read one byte and the text axis with one.
The bounds check lives in the lowered form which raises an PANIC IndexOutOfBoundsError out of range, mirroring String's code-point operator []. Delegating rather than range-checking here is deliberate: the array's PANIC carries the offending index and the bound in its message, and this class sits upstream of Formatter, so a PANIC written here could only say "out of bounds" with no numbers in it.
METHOD equals(REFERENCE ByteBuffer other) RETURNS booleanreads
COMPARISON Value equality, delegated to the value array's own equals. That is not merely shorter: for an element type with a unique object representation the array compares with a single length-checked memcmp (one SIMD compare) where this method used to walk element by element. Measured at 6x faster on 64 elements and 11-14x from 1K up, with identical results across an 8-cell differential matrix — including the float guard, since the array deliberately does NOT memcmp an arithmetic element type (-0.0 == +0.0, NaN != NaN would come out wrong).
METHOD isLessThan(REFERENCE ByteBuffer other) RETURNS booleanreads
Use the lexicographic comparision below
METHOD compareTo(REFERENCE ByteBuffer other) RETURNS int32reads
Lexicographic byte comparison: shorter buffer orders before a longer one when prefixes match. Returns -1 / 0 / 1.
METHOD find(REFERENCE ByteBuffer needle) RETURNS | int64reads
Searchable — first index at which needle's bytes occur in this
buffer, else FAILURE. Forwards to the one canonical binary scan in
ByteBufferView: a full-span view over this buffer searches for
needle's bytes.
METHOD lastIndexOf(REFERENCE ByteBuffer needle) RETURNS | int64reads
Index of the LAST occurrence of needle, pipe-XOR. The mirror of
find, forwarded through a full-span view the same way, so there is
exactly one byte scan in the kernel.
METHOD find_first_of(REFERENCE ByteBuffer set) RETURNS | int64reads
B1: index of the first byte that IS a member of set (the bytes of
set, treated as a set). Forwards through a full-span view.
METHOD find_first_not_of(REFERENCE ByteBuffer set) RETURNS | int64reads
B1: index of the first byte that is NOT a member of set.
METHOD view(int64 start, int64 length) RETURNS ByteBufferViewreads
Viewable — a non-owning, bounded window over this buffer's bytes
without copying. The byte-side analogue of String.view.
METHOD hash() RETURNS uint64reads
HASHING — same FNV-1a as String, deterministic across runs FNV-1a 64-bit hash. Matches String.hash() and DynamicString.hash() byte-for-byte for identical content, so the three classes hash to the same uint64 when carrying the same bytes.
METHOD hash(uint64 seed) RETURNS uint64reads
Seeded FNV-1a, the peer of String.hash(uint64 seed). Chaining a seed
lets a composite key hash its parts in sequence without materialising a
concatenation.
METHOD contains(REFERENCE ByteBuffer needle) RETURNS booleanreads
CONTENT LOOKUP Empty needle returns true (matches String.contains).
METHOD startsWith(REFERENCE ByteBuffer prefix) RETURNS booleanreads
METHOD endsWith(REFERENCE ByteBuffer suffix) RETURNS booleanreads
METHOD find(REFERENCE ByteBuffer needle, int64 fromIndex) RETURNS | int64reads
First-occurrence index at or after fromIndex. Pipe-XOR:
FAILURE on out-of-range fromIndex or when needle does not
occur from that point onward.
METHOD count(REFERENCE ByteBuffer needle) RETURNS int64reads
Non-overlapping occurrence count. Empty needle returns 0 (avoids infinite-match scenario).
METHOD subBuffer(int64 start, int64 length) RETURNS ByteBufferreads
SLICING / CONCATENATION
Copy a contiguous slice into a fresh ByteBuffer. start is inclusive,
length is a byte count. TOTAL, and the exact peer of
String.substring: a bad range is a precondition violation — a
programming error — so it raises a PANIC, the same category as [].
length == 0 yields an empty buffer and is not an error.
This returned pipe-XOR (ByteBuffer | STATUS) until Phase 3, which made
a caller slicing a buffer write an IF where the same caller slicing a
String writes none. A recoverable outcome is a search that misses; a
caller asking for bytes that were never there is a bug in the caller.
METHOD concat(REFERENCE ByteBuffer other) RETURNS ByteBufferreads
Concatenation. Returns a fresh ByteBuffer; receivers unchanged. operator + pending — see.
METHOD iterator() RETURNS ByteBufferIteratorreads
Yield a value-iterator over the bytes. The iterator copies the bytes into its own storage at construction — it is fully independent of this buffer for its whole lifetime.
METHOD data() RETURNS REFERENCE binary[]reads
Non-owning REFERENCE to the underlying binary[] storage. The
receiver retains ownership; the returned reference is valid
for the receiver's lifetime per §11.6 lifetime elision. The
canonical use is at a FOREIGN BIND call site that needs to
expose the byte storage to a C function without copying.