envzn
0.8 · beta · not released

Library / Strings / Bytes / ByteBuffer

CLASSIMPLEMENTS Countable, Cloneable, Hashable, Equatable<ByteBuffer>, Comparable<ByteBuffer>, Searchable<ByteBuffer>, Viewable

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

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 boolean
reads

INSPECTION

METHOD size() RETURNS int64
reads
METHOD length() RETURNS int64
reads

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 binary
reads

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 boolean
reads

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 boolean
reads

Use the lexicographic comparision below

METHOD compareTo(REFERENCE ByteBuffer other) RETURNS int32
reads

Lexicographic byte comparison: shorter buffer orders before a longer one when prefixes match. Returns -1 / 0 / 1.

METHOD find(REFERENCE ByteBuffer needle) RETURNS | int64
reads

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 | int64
reads

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 | int64
reads

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 | int64
reads

B1: index of the first byte that is NOT a member of set.

METHOD view(int64 start, int64 length) RETURNS ByteBufferView
reads

Viewable — a non-owning, bounded window over this buffer's bytes without copying. The byte-side analogue of String.view.

METHOD hash() RETURNS uint64
reads

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 uint64
reads

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 boolean
reads

CONTENT LOOKUP Empty needle returns true (matches String.contains).

METHOD startsWith(REFERENCE ByteBuffer prefix) RETURNS boolean
reads
METHOD endsWith(REFERENCE ByteBuffer suffix) RETURNS boolean
reads
METHOD find(REFERENCE ByteBuffer needle, int64 fromIndex) RETURNS | int64
reads

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 int64
reads

Non-overlapping occurrence count. Empty needle returns 0 (avoids infinite-match scenario).

METHOD subBuffer(int64 start, int64 length) RETURNS ByteBuffer
reads

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

Concatenation. Returns a fresh ByteBuffer; receivers unchanged. operator + pending — see.

METHOD iterator() RETURNS ByteBufferIterator
reads

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.