Library / Strings / Text / DynamicString
DynamicString
Stack-resident mutable text builder.
Constructors 5
INIT()INIT(int64 reserve)
Pre-size the builder to reserve code points, so a build of known
length performs ONE allocation instead of walking the growth schedule.
This was a NO-OP: it accepted the number and discarded it, on the
grounds that "pre-spilling to capacity N would need an storage reserve
method". reserveExact is that method — the substrate's resize already
takes INLINE and handles the spill, so the storage was never the
obstacle. Every caller that believed it was pre-sizing has been growing
from zero.
reserveExact, not reserve: this is a STATED size. reserve is the
incremental hint append uses and deliberately leaves 79% headroom.
INIT(REFERENCE String s)
Bridge ctor — start with the contents of an immutable String. Both storages are UTF-32 code points, so this is a direct copy with no encode step.
REFERENCE: the source is borrowed and survives construction. It used
to be taken by value, which handed the constructor a whole String it
only ever read from.
INIT(REFERENCE DynamicString other)
Copy-construct from another DynamicString. 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 char32[] origin)
Construct from a raw code-point array, COPYING it. REFERENCE, so the
source is borrowed and the builder allocates its own storage — the same
rule the other three owning classes in this family follow.
Methods 53
METHOD clone() RETURNS DynamicStringreads
Deep copy. Returns a fresh DynamicString with the same codepoints. Implements the Cloneable contract.
METHOD isEmpty() RETURNS booleanreads
O(1) emptiness test.
METHOD length() RETURNS int64reads
Code-point count, O(1). Storage is one codepoint per slot.
METHOD size() RETURNS int64reads
UTF-8 byte count of the stored text — distinct from length() (the code-point count). Storage is UTF-32 code points (Phase 8.7), so size() sums each code point's UTF-8 width per RFC 3629 (the same widths UTFCodec.encodeToUTF8 emits): U+0000–007F → 1 byte, U+0080–07FF → 2, U+0800–FFFF → 3, ≥ U+10000 → 4.
METHOD __op_index__(int64 i) RETURNS char32reads
Code point at index i. Declared as operator [] so the
only access syntax is s[i] — there is no public at()
method on DynamicString. Raises IndexOutOfBoundsError if i is out
of range — bounds check lives in _ValueArray<char32_t>::operator[].
METHOD equals(REFERENCE DynamicString other) RETURNS booleanreads
Compare codepoint content against another DynamicString. 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 equals(REFERENCE String other) RETURNS booleanreads
Compare codepoint content against a String. Direct compare — both storages are UTF-32 codepoints.
METHOD isLessThan(REFERENCE DynamicString other) RETURNS booleanreads
Lexicographic codepoint comparison against another DynamicString.
METHOD compareTo(REFERENCE String other) RETURNS int32reads
Lexicographic codepoint comparison against a String. Returns -1/0/+1.
METHOD compareTo(REFERENCE char32[] otherData) RETURNS int32reads
Lexicographic codepoint comparison against a String. Returns -1/0/+1.
METHOD hash() RETURNS uint64reads
FNV-1a 64-bit hash over the UTF-32 codepoints. Matches String.hash() for identical text content (both fold over the same codepoint sequence).
METHOD hash(uint64 seed) RETURNS uint64reads
FNV-1a 64-bit hash with caller-supplied seed.
METHOD find(REFERENCE DynamicString needle) RETURNS | int64reads
First occurrence of needle in this DynamicString. Pipe-XOR:
SUCCESS yields the codepoint index of the match; FAILURE means no
match. This is the Searchable contract (case-sensitive). The scan is
the one canonical char32 scan in StringView — DynamicString builds a
full-span view over its own codepoints and forwards. A String-needle
overload is provided for convenience.
METHOD find(REFERENCE DynamicString needle, boolean caseMatch) RETURNS | int64reads
As find, with ASCII case-fold when caseMatch == FALSE. Views both
sides in place and runs the one canonical char32 scan in StringView.
This method used to snapshot BOTH sides to immutable Strings — two full
copies per call — on the belief that a char32[128+] field could not
bind to a REFERENCE char32[] parameter. E3 disproved it:
since SBO was removed both spellings are the same EvArray<char32_t>.
METHOD find(REFERENCE String needle) RETURNS | int64reads
Convenience: search for a String needle.
METHOD find(REFERENCE String needle, boolean caseMatch) RETURNS | int64reads
As find, with ASCII case-fold when caseMatch == FALSE. Views the
storage in place — no snapshot — and forwards to the canonical scan,
which owns the native fast path and its bounds re-derivation.
METHOD contains(REFERENCE String needle) RETURNS booleanreads
True iff needle occurs at least once (case-sensitive).
METHOD contains(REFERENCE String needle, boolean caseMatch) RETURNS booleanreads
METHOD count(REFERENCE String needle) RETURNS int64reads
Non-overlapping occurrence count of needle (case-sensitive).
Empty needle returns 0.
METHOD count(REFERENCE String needle, boolean caseMatch) RETURNS int64reads
METHOD view(int64 start, int64 len) RETURNS StringViewreads
Viewable — a non-owning, bounded window over this builder's code points
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 String.view.
METHOD startsWith(REFERENCE String prefix) RETURNS booleanreads
True iff this builder begins with prefix.
Builds a StringView directly over .data — no snapshot. E3
established that a char32[128+] field binds to a REFERENCE char32[]
parameter: both lower to EvArray<char32_t>, and have since SBO was
removed. The view is a local, consumed before this method returns, and
nothing mutates the builder in between — so it needs none of the
mutation-lock machinery that a PUBLIC view() will require, and it
costs no copy. find above uses the same shape.
METHOD endsWith(REFERENCE String suffix) RETURNS booleanreads
True iff this builder ends with suffix.
METHOD lastIndexOf(REFERENCE String needle) RETURNS | int64reads
Index of the LAST occurrence of needle, pipe-XOR.
METHOD find_first_of(REFERENCE String set) RETURNS | int64reads
Index of the first code point that IS a member of set, pipe-XOR.
METHOD find_first_not_of(REFERENCE String set) RETURNS | int64reads
Index of the first code point that is NOT a member of set, pipe-XOR.
METHOD split(REFERENCE String delim) RETURNS String[]reads
Split on delim into an array of Strings. Empty delim
returns a single-element array containing a snapshot of this
DynamicString. Adjacent delimiters produce empty pieces; a
trailing delimiter produces an empty trailing piece. Receiver
is not mutated.
METHOD splitLines() RETURNS String[]reads
Split into lines on any of the Unicode line boundaries (same set as String.splitLines): LF, VT, FF (0x0A-0x0C), FS, GS, RS (0x1C-0x1E), CR and CR-LF (one boundary), NEL (U+0085), LS (U+2028), PS (U+2029). Terminators are NOT included; a trailing terminator does not yield a trailing empty piece. Receiver not mutated.
METHOD concat(REFERENCE String other) RETURNS Stringreads
Build a fresh String from this DynamicString's content followed
by other's. Non-modifying — receiver and other are both
unchanged. (To append in place, use the modifying append(String)
below.)
METHOD iterator() RETURNS ValueIterator[char32]reads
Snapshot to a String first, then return its iterator. The snapshot is an O(n) codepoint copy; subsequent iteration is O(1) per codepoint against the contiguous char32[] storage.
METHOD format(FormatArgument args...) RETURNS Stringreads
Format this text as a template. Compiled as
Formatter.format(<this>->toString(), …) — the one format renderer
(analyze/format_calls.py; format-argument-design.md §6) — so this body is
never reached. It names no Formatter: the conversion hosts depend on
DynamicString, and Formatter on them.
METHOD formatWith(BinaryMode mode, FormatArgument args...) RETURNS Stringreads
METHOD toString() RETURNS Stringreads
BRIDGE OUT — explicit snapshot to immutable String ----------- Direct codepoint copy into a fresh String. No decode step.
MODIFY METHOD toUpper() RETURNS STATUSmodifies
─── MODIFYING METHODS ───────────────────────────────────────── Mutate receiver in place; return STATUS. ASCII uppercase fold, in place. Codepoints >= 0x80 pass through. Full Unicode case mapping is V2.
MODIFY METHOD toLower() RETURNS STATUSmodifies
ASCII lowercase fold, in place.
MODIFY METHOD toTitleCase() RETURNS STATUSmodifies
ASCII title-case fold, in place: the first character of each word is
uppercased and the remainder of the word lowercased. Word boundaries are
ASCII whitespace, -, and ' (see isTitleBoundary). Codepoints >= 0x80
pass through uncased but do not break a word. Full Unicode case mapping is
V2 — the same limit toUpper / toLower carry.
MODIFY METHOD trim() RETURNS STATUSmodifies
Strip ASCII whitespace at both ends, in place.
MODIFY METHOD trimStart() RETURNS STATUSmodifies
MODIFY METHOD trimEnd() RETURNS STATUSmodifies
METHOD substring(int64 start, int64 len) RETURNS Stringreads
A NEW String over [start, start+length). PURE — the receiver is
untouched. Matches String.substring, which PANICs on a bad range
rather than returning a STATUS, so this does too.
MODIFY METHOD append(REFERENCE String s) RETURNS STATUSmodifies
BUILDER MUTATIONS — append ------------------------------------
MODIFY METHOD append(DynamicString d) RETURNS STATUSmodifies
MODIFY METHOD append(char32 c) RETURNS STATUSmodifies
Append one Unicode code point. Tier-1 text check rejects a noncharacter / surrogate / control code point with FAILURE.
MODIFY METHOD setAt(int64 i, char32 c) RETURNS STATUSmodifies
Assign the code point at i. Pipe-XOR on the index, and gated by the
same Tier-1 text check append(char32) applies — a DynamicString may
not be mutated into holding a surrogate, noncharacter or control.
int64, not the uint64 DynamicByteBuffer.setAt still takes; Phase 2
normalises that split and a new method should not join the wrong side.
MODIFY METHOD clear() RETURNS STATUSmodifies
Empty the builder, keeping its capacity. The mutable text class had no way to be cleared at all, while its byte peer did.
MODIFY METHOD truncate(int64 n) RETURNS STATUSmodifies
Drop code points from the END until length() == n. FAILURE if n
exceeds the current length or is negative — this never grows.
MODIFY METHOD dropFirst(int64 n) RETURNS STATUSmodifies
Drop the first n code points. O(length - n) shift left.
MODIFY METHOD prepend(REFERENCE String s) RETURNS STATUSmodifies
BUILDER MUTATIONS — prepend -----------------------------------
MODIFY METHOD prepend(DynamicString d) RETURNS STATUSmodifies
MODIFY METHOD prepend(char32 c) RETURNS STATUSmodifies
MODIFY METHOD replace(REFERENCE String needle, REFERENCE String replacement) RETURNS STATUSmodifies
BUILDER MUTATIONS — replace -----------------------------------
Replace every occurrence of needle with replacement, in
place. Empty needle returns FAILURE (avoids infinite-substitution).
MODIFY METHOD padStart(int64 targetLength, char32 padChar) RETURNS STATUSmodifies
BUILDER MUTATIONS — padStart / padEnd -------------------------
Left-pad with padChar until the receiver is targetLength
CODE POINTS long. Already-longer receivers are left alone.
MODIFY METHOD padEnd(int64 targetLength, char32 padChar) RETURNS STATUSmodifies
Right-pad with padChar until the receiver is targetLength
CODE POINTS long.