Library / Strings / Bytes / 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 DynamicByteBufferreads
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 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 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 ByteBufferIteratorreads
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 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 DynamicByteBuffer other) RETURNS booleanreads
Use the lexicographic comparison below.
METHOD compareTo(REFERENCE DynamicByteBuffer other) RETURNS int32reads
Lexicographic byte comparison. Shorter buffer orders before longer when prefixes match. Returns -1 / 0 / 1.
METHOD find(REFERENCE DynamicByteBuffer needle) RETURNS | int64reads
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 uint64reads
HASHING FNV-1a 64-bit hash. Matches String.hash() / DynamicString.hash() / ByteBuffer.hash() byte-for-byte for identical content.
METHOD hash(uint64 seed) RETURNS uint64reads
METHOD contains(REFERENCE ByteBuffer needle) RETURNS booleanreads
CONTENT LOOKUP
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).
MODIFY METHOD append(binary b) RETURNS STATUSmodifies
MUTATIONS — return STATUS, mutate receiver in place
MODIFY METHOD append(REFERENCE ByteBuffer bb) RETURNS STATUSmodifies
MODIFY METHOD append(DynamicByteBuffer dbb) RETURNS STATUSmodifies
MODIFY METHOD prepend(binary b) RETURNS STATUSmodifies
MODIFY METHOD prepend(REFERENCE ByteBuffer bb) RETURNS STATUSmodifies
MODIFY METHOD setAt(int64 i, binary b) RETURNS STATUSmodifies
MODIFY METHOD clear() RETURNS STATUSmodifies
MODIFY METHOD truncate(int64 n) RETURNS STATUSmodifies
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 STATUSmodifies
Drop the first n bytes. O(size - n) shift left.
METHOD subBuffer(int64 start, int64 length) RETURNS ByteBufferreads
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 binaryreads
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 ByteBufferViewreads
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 | int64reads
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 | int64reads
Index of the first byte that IS a member of set, pipe-XOR.
METHOD find_first_not_of(REFERENCE ByteBuffer set) RETURNS | int64reads
Index of the first byte that is NOT a member of set, pipe-XOR.
METHOD concat(REFERENCE ByteBuffer other) RETURNS ByteBufferreads
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 STATUSmodifies
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 STATUSmodifies
Pad the END with padByte until the buffer is targetLength long.
MODIFY METHOD replace(REFERENCE ByteBuffer needle, REFERENCE ByteBuffer replacement) RETURNS STATUSmodifies
Replace every occurrence of needle with replacement. Empty
needle returns FAILURE (avoids infinite-substitution).
METHOD toByteBuffer() RETURNS ByteBufferreads
BRIDGE OUT — explicit snapshot to immutable ByteBuffer