envzn
0.8 · beta · not released

Library / Strings / Bytes / DynamicByteBuffer

CLASSIMPLEMENTS Countable, Cloneable, Hashable, Equatable<DynamicByteBuffer>, Comparable<DynamicByteBuffer>, Searchable<DynamicByteBuffer>

DynamicByteBuffer

Stack-resident mutable binary builder.

Constructors 5

INIT()

CONSTRUCTORS / CLEANUP

INIT(int64 reserve)

Pre-size the builder to reserve bytes — one allocation instead of the growth schedule. that is reserveExact, and the substrate's resize already handles the INLINE spill. reserveExact and not reserve because this is a STATED size, not the incremental hint append uses.

INIT(REFERENCE binary[] origin)

Construct from a raw byte array, COPYING it. DynamicString has had a raw-array constructor all along; the byte builder had none, so the only way in was append-in-a-loop.

REFERENCE, not owning: the class allocates its own storage rather than adopting the caller's. That is what every kernel class does — the last owning constructor in this family, ByteBuffer's, was retired in Phase 2.

INIT(REFERENCE DynamicByteBuffer other)

Copy-construct from another DynamicByteBuffer. Every owning class in the text/binary family now has a same-type copy constructor: String, ByteBuffer, DynamicString and DynamicByteBuffer.

REFERENCE, so the source is borrowed and this instance allocates its own storage. It does NOT collide with the other constructors here — they differ in parameter TYPE, which C++ overload resolution separates. What it cannot separate is one type owned against REFERENCE; that is why there is no owning companion anywhere in this family.

INIT(REFERENCE ByteBuffer other)

Methods 37

METHOD clone() RETURNS DynamicByteBuffer
reads

CLONE — hand-written. Constructs a fresh DynamicByteBuffer and re-appends every byte through the public append() method, so we stay on the same write path as ordinary growth (no cross- instance private-field access). Mirrors DynamicString.clone().

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 data() RETURNS REFERENCE binary[]
reads

Non-owning REFERENCE to the underlying binary[512+] storage. Mirror of ByteBuffer.data() (§11.6 lifetime elision applies); canonical use is at a FOREIGN BIND call site that needs to expose the byte storage to a C function without copying.

METHOD iterator() RETURNS ByteBufferIterator
reads

Snapshot iterator over the current bytes. Returns the shared ByteBufferIterator (the value-form ValueIterator OF binary used by ByteBuffer too): it copies the bytes in at construction, so the walk stays stable even if this mutable buffer is appended to afterward.

METHOD equals(REFERENCE DynamicByteBuffer 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 DynamicByteBuffer other) RETURNS boolean
reads

Use the lexicographic comparison below.

METHOD compareTo(REFERENCE DynamicByteBuffer other) RETURNS int32
reads

Lexicographic byte comparison. Shorter buffer orders before longer when prefixes match. Returns -1 / 0 / 1.

METHOD find(REFERENCE DynamicByteBuffer needle) RETURNS | int64
reads

Searchable — first index at which needle's bytes occur in this buffer, else FAILURE. Snapshots both sides to immutable ByteBuffers and forwards to ByteBuffer.find — the one canonical byte scan.

METHOD hash() RETURNS uint64
reads

HASHING FNV-1a 64-bit hash. Matches String.hash() / DynamicString.hash() / ByteBuffer.hash() byte-for-byte for identical content.

METHOD hash(uint64 seed) RETURNS uint64
reads
METHOD contains(REFERENCE ByteBuffer needle) RETURNS boolean
reads

CONTENT LOOKUP

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

MODIFY METHOD append(binary b) RETURNS STATUS
modifies

MUTATIONS — return STATUS, mutate receiver in place

MODIFY METHOD append(REFERENCE ByteBuffer bb) RETURNS STATUS
modifies
MODIFY METHOD append(DynamicByteBuffer dbb) RETURNS STATUS
modifies
MODIFY METHOD prepend(binary b) RETURNS STATUS
modifies
MODIFY METHOD prepend(REFERENCE ByteBuffer bb) RETURNS STATUS
modifies
MODIFY METHOD setAt(int64 i, binary b) RETURNS STATUS
modifies
MODIFY METHOD clear() RETURNS STATUS
modifies
MODIFY METHOD truncate(int64 n) RETURNS STATUS
modifies

Drop bytes from the END until size() == n. FAILURE if n exceeds current size or n < 0 (no-grow contract).

MODIFY METHOD dropFirst(int64 n) RETURNS STATUS
modifies

Drop the first n bytes. O(size - n) shift left.

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

A NEW ByteBuffer over [start, start+length). PURE — the receiver is untouched. Same name, same meaning and same shape as ByteBuffer.subBuffer, which is what the vertical rule requires — TOTAL Raising a PANIC on a bad range like String.substring does.

METHOD __op_index__(int64 i) RETURNS binary
reads

Byte at i. Throws IndexOutOfBoundsError out of range — the bounds check lives in the value array's own subscript, exactly as ByteBuffer's and String's do. The mutable class had no index operator at all, so dbb[i] did not compile while bb[i] did.

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

Viewable — a non-owning, bounded window over this builder's bytes without copying. The mutable half of the family had no view() until Phase 5, because a view into a GROWABLE buffer is only safe once the analyzer refuses to mutate the source while the view is live.

That lock now exists: a view() on a named variable arms the same per-source mutation lock an iterator() does (E5003), so appending to or truncating this builder while a view over it is in scope is a compile-time error rather than a stale window.

What the lock does NOT cover is the view outliving this object — that is, it predates this method, and it already applies to ByteBuffer.view.

METHOD lastIndexOf(REFERENCE ByteBuffer needle) RETURNS | int64
reads

Index of the LAST occurrence of needle, pipe-XOR. Scans in place over the backing rather than snapshotting to a ByteBuffer first — the same choice find already makes here, and the one DynamicString.find still does not. Once view() reaches the mutable classes this can forward to ByteBufferView.lastIndexOf like the immutable peer does.

METHOD find_first_of(REFERENCE ByteBuffer set) RETURNS | int64
reads

Index of the first byte that IS a member of set, pipe-XOR.

METHOD find_first_not_of(REFERENCE ByteBuffer set) RETURNS | int64
reads

Index of the first byte that is NOT a member of set, pipe-XOR.

METHOD concat(REFERENCE ByteBuffer other) RETURNS ByteBuffer
reads

A NEW ByteBuffer holding this buffer's bytes followed by other's. Pure: this buffer is unchanged. The mutating sibling is append.

MODIFY METHOD padStart(int64 targetLength, binary padByte) RETURNS STATUS
modifies

Pad the FRONT with padByte until the buffer is targetLength long. Already at or above the target is SUCCESS and a no-op. int64 rather than the uint64 DynamicString still uses — the sign split across these two classes is normalised in Phase 2, and a new method should not be born on the wrong side of it.

MODIFY METHOD padEnd(int64 targetLength, binary padByte) RETURNS STATUS
modifies

Pad the END with padByte until the buffer is targetLength long.

MODIFY METHOD replace(REFERENCE ByteBuffer needle, REFERENCE ByteBuffer replacement) RETURNS STATUS
modifies

Replace every occurrence of needle with replacement. Empty needle returns FAILURE (avoids infinite-substitution).

METHOD toByteBuffer() RETURNS ByteBuffer
reads

BRIDGE OUT — explicit snapshot to immutable ByteBuffer