envzn
0.8 · beta · not released

Library / Strings / Text / DynamicString

CLASSIMPLEMENTS Countable, Cloneable, Hashable, Equatable<DynamicString>, Comparable<DynamicString>, Searchable<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 DynamicString
reads

Deep copy. Returns a fresh DynamicString with the same codepoints. Implements the Cloneable contract.

METHOD isEmpty() RETURNS boolean
reads

O(1) emptiness test.

METHOD length() RETURNS int64
reads

Code-point count, O(1). Storage is one codepoint per slot.

METHOD size() RETURNS int64
reads

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

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

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

Compare codepoint content against a String. Direct compare — both storages are UTF-32 codepoints.

METHOD isLessThan(REFERENCE DynamicString other) RETURNS boolean
reads

Lexicographic codepoint comparison against another DynamicString.

METHOD compareTo(REFERENCE String other) RETURNS int32
reads

Lexicographic codepoint comparison against a String. Returns -1/0/+1.

METHOD compareTo(REFERENCE char32[] otherData) RETURNS int32
reads

Lexicographic codepoint comparison against a String. Returns -1/0/+1.

METHOD hash() RETURNS uint64
reads

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

FNV-1a 64-bit hash with caller-supplied seed.

METHOD find(REFERENCE DynamicString needle) RETURNS | int64
reads

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

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

Convenience: search for a String needle.

METHOD find(REFERENCE String needle, boolean caseMatch) RETURNS | int64
reads

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

True iff needle occurs at least once (case-sensitive).

METHOD contains(REFERENCE String needle, boolean caseMatch) RETURNS boolean
reads
METHOD count(REFERENCE String needle) RETURNS int64
reads

Non-overlapping occurrence count of needle (case-sensitive). Empty needle returns 0.

METHOD count(REFERENCE String needle, boolean caseMatch) RETURNS int64
reads
METHOD view(int64 start, int64 len) RETURNS StringView
reads

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

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

True iff this builder ends with suffix.

METHOD lastIndexOf(REFERENCE String needle) RETURNS | int64
reads

Index of the LAST occurrence of needle, pipe-XOR.

METHOD find_first_of(REFERENCE String set) RETURNS | int64
reads

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

METHOD find_first_not_of(REFERENCE String set) RETURNS | int64
reads

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

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

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 String
reads
METHOD toString() RETURNS String
reads

BRIDGE OUT — explicit snapshot to immutable String ----------- Direct codepoint copy into a fresh String. No decode step.

MODIFY METHOD toUpper() RETURNS STATUS
modifies

─── 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 STATUS
modifies

ASCII lowercase fold, in place.

MODIFY METHOD toTitleCase() RETURNS STATUS
modifies

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 STATUS
modifies

Strip ASCII whitespace at both ends, in place.

MODIFY METHOD trimStart() RETURNS STATUS
modifies
MODIFY METHOD trimEnd() RETURNS STATUS
modifies
METHOD substring(int64 start, int64 len) RETURNS String
reads

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 STATUS
modifies

BUILDER MUTATIONS — append ------------------------------------

MODIFY METHOD append(DynamicString d) RETURNS STATUS
modifies
MODIFY METHOD append(char32 c) RETURNS STATUS
modifies

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 STATUS
modifies

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 STATUS
modifies

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 STATUS
modifies

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 STATUS
modifies

Drop the first n code points. O(length - n) shift left.

MODIFY METHOD prepend(REFERENCE String s) RETURNS STATUS
modifies

BUILDER MUTATIONS — prepend -----------------------------------

MODIFY METHOD prepend(DynamicString d) RETURNS STATUS
modifies
MODIFY METHOD prepend(char32 c) RETURNS STATUS
modifies
MODIFY METHOD replace(REFERENCE String needle, REFERENCE String replacement) RETURNS STATUS
modifies

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 STATUS
modifies

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 STATUS
modifies

Right-pad with padChar until the receiver is targetLength CODE POINTS long.