Library / Strings / Text / String
String
Immutable readable/printable text.
Constructors 4
INIT()Empty String.
INIT(REFERENCE char32[] origin)
Take ownership of a pre-built code-point array. The literal-
lowering path in the emitter and every internal transformation
(substring, toUpper, trim*, …) construct their result
this way: build a fresh char32[], hand it to a new String.
From a raw code-point array, COPYING it. REFERENCE is now explicit:
it always lowered to const EvArray<char32_t>&, so this states the
borrow the signature already had rather than changing it.
INIT(char32[] origin, int64 length)
THE LITERAL CONSTRUCTOR. The emitter's, not a developer's.
It could not be hidden. INTERNAL INIT is E1141 and PRIVATE INIT is a
parse error: a constructor carries no visibility modifier in Envzn,
because "INIT and CLEANUP are lifecycle, not module surface". So this is
public, and what keeps it honest is its own signature: the array
is a plain, owning parameter — a developer who calls it sees that it is taken, and
the analyzer poisons the source so a later read is E3010. That is the
language's normal contract rather than a hidden trapdoor.
It exists to spend ONE allocation on a string literal instead of two.
String s = "bob" lowers to a _ValueArray<char32_t>(U"bob", 3)
handed to a String constructor. Through INIT(REFERENCE char32[]) above
that array is built, then COPIED into .data and destroyed — two heap
allocations and two memcpys for every literal in the program, of which
there are ~2,800. Taking it as a plain (owning) parameter makes it a by-value
EvArray<char32_t>, so C++17's guaranteed copy elision constructs the
caller's prvalue DIRECTLY into it — nothing is materialised twice — and
:= then transfers the buffer pointer into .data. Measured 2 -> 1.
length IS REDUNDANT AND MUST NOT BE REMOVED. origin.length already
carries the count; this parameter exists solely to give this INIT a
different ARITY from INIT(REFERENCE char32[]). Owning and REFERENCE of
the SAME type at the SAME arity both lower to a one-argument
constructor over EvArray<char32_t> — by value and by const reference —
and clang rejects the pair as ambiguous. Differing arity is the
established way round it; StringIterator carries both forms for
exactly this reason. Delete this parameter and the kernel stops building.
It is String-only on purpose: a character-sequence literal has exactly
one representation in the language, and it is String. The other five
text/binary classes do not get it, which
run_text_binary_consistency.sh records as an allow-listed asymmetry
rather than drift.
INIT(REFERENCE String other)
Copy-construct from another String. ByteBuffer has had
INIT(REFERENCE ByteBuffer) all along; the text axis had no equivalent,
so CREATE String(other) was rejected outright until Phase 1 added this.
This does NOT collide with the array form above: the two differ in
parameter TYPE (String against char32[]), which C++ overload
resolution separates cleanly. What it cannot separate is the same type
owned versus REFERENCE — both lower to one-argument
constructors taking EvArray<char32_t> by value and by const reference,
and clang calls that ambiguous. That is why there is no owning companion.
Methods 33
METHOD clone() RETURNS Stringreads
Cloneable contract — deep copy. Returns a fresh String whose
.data is an independent code-point array with the same values.
METHOD length() RETURNS int64reads
Code-point count. O(1).
METHOD size() RETURNS int64reads
UTF-8 byte count of the text — distinct from length() (the code-point count). Storage is UTF-32 code points, 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. Mirrors DynamicString.size().
METHOD isEmpty() RETURNS booleanreads
True iff the String has zero code points.
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 String. Raises IndexOutOfBoundsError if i is out
of range — bounds check lives in _ValueArray<char32_t>::operator[].
METHOD equals(REFERENCE String other) RETURNS booleanreads
Code-point-by-code-point equality. UTF-32 storage means no normalisation surprises; two Strings are equal iff their code- point sequences match exactly. 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 String other) RETURNS booleanreads
Use the lexicographic comparision below
METHOD compareTo(REFERENCE String other) RETURNS int32reads
Lexicographic code-point comparison. Returns -1 / 0 / +1 in the usual three-way-comparison sense.
METHOD hash() RETURNS uint64reads
FNV-1a 64-bit hash over the code-point array. Satisfies the Hashable contract. Deterministic.
METHOD hash(uint64 seed) RETURNS uint64reads
FNV-1a 64-bit hash with caller-supplied seed. Each code point is mixed in as a 4-byte little-endian sequence: XOR then multiply per byte. Wrap on uint64 overflow is the algorithm.
METHOD substring(int64 start, int64 len) RETURNS Stringreads
Substring by code-point index. start is inclusive; length is
the count of code points. A bad range is a precondition violation
(programming error) — it PANICs, the same category as operator[].
Recoverable runtime outcomes (search misses) live on find/count
as the pipe-XOR (... | STATUS); a bad slice range is not one.
Also the lowering target of the s[start:length] slice sugar.
METHOD view(int64 start, int64 length) RETURNS StringViewreads
Non-owning bounded view starting at start for length code
points. Suitable for searching / scanning without allocating a
copy. StringView's INIT validates the bounds; length == 0
yields an empty view; negative or out-of-range bounds PANIC.
METHOD find(REFERENCE String needle) RETURNS | int64reads
First occurrence of needle in this String (case-sensitive) — the
Searchable contract. Pipe-XOR: SUCCESS yields the absolute index
where the match begins; FAILURE means no match. To search a
sub-range, view(start, length) then search the window.
METHOD find(REFERENCE String needle, boolean caseMatch) RETURNS | int64reads
As find, with ASCII case-fold when caseMatch == FALSE. Forwards to
the one canonical char32 scan in StringView: a full-span view over this
String's codepoints searches for needle's codepoints.
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 startsWith(REFERENCE String prefix) RETURNS booleanreads
True iff this String begins with prefix. Forwards to the one canonical
char32 scan in StringView, the same way find does — a full-span view
over this String's code points tests prefix's code points. An empty
prefix is a prefix of everything.
METHOD endsWith(REFERENCE String suffix) RETURNS booleanreads
True iff this String ends with suffix. Same delegation as startsWith.
METHOD lastIndexOf(REFERENCE String needle) RETURNS | int64reads
Index of the LAST occurrence of needle, pipe-XOR: SUCCESS populates
index, FAILURE when the needle does not occur. The forward search is
find; this is its mirror, and like find it forwards to StringView so
there is exactly one char32 scan in the kernel.
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 find_first_of(REFERENCE String set) RETURNS | int64reads
B1: index of the first code point that IS a member of set (the code
points of set, treated as a set). Pipe-XOR: SUCCESS = index, FAILURE =
none present. Forwards through a full-span view to the one canonical
char32 scan in StringView.
METHOD find_first_not_of(REFERENCE String set) RETURNS | int64reads
B1: index of the first code point that is NOT a member of set.
METHOD split(REFERENCE String delim) RETURNS String[]reads
Split on delim into an array of Strings. Adjacent delimiters
produce empty pieces; a trailing delimiter produces an empty
trailing piece. Empty receiver returns a single-element array
containing one empty String. Empty delim returns a single-
element array containing this String unchanged.
METHOD splitLines() RETURNS String[]reads
Split on any of the Unicode line-break code points: LF, CR, CRLF (one boundary), VT, FF, NEL (U+0085), LS (U+2028), PS (U+2029). The line terminators are NOT included in the pieces. A trailing terminator does NOT yield a trailing empty piece.
METHOD toUpper() RETURNS Stringreads
ASCII uppercase fold. Code points >= 0x80 unchanged.
METHOD toLower() RETURNS Stringreads
ASCII lowercase fold. Code points >= 0x80 unchanged.
METHOD trim() RETURNS Stringreads
TRIM (ASCII WHITESPACE: space, tab, LF, CR, VT, FF) -----------
METHOD trimStart() RETURNS Stringreads
METHOD trimEnd() RETURNS Stringreads
METHOD format(FormatArgument args...) RETURNS Stringreads
Format this String as a template — substitute $1..$9 with the
corresponding argument, $$ with a literal $ and $: with a literal
:; a placeholder may carry a :spec (stdio-spec.md §4). The everyday
("text $1")->format(a) form.
One renderer does every format call: Formatter. The compiler compiles a
format call on a String as Formatter.format(template, …)
(analyze/format_calls.py; format-argument-design.md §6, Q2), so the
template is read in place and this body is never reached. It names no
Formatter, which keeps String free of every kernel dependency — the
invariant the kernel's header order rests on.
METHOD formatWith(BinaryMode mode, FormatArgument args...) RETURNS Stringreads
format with an explicit rendering mode for binary / byte-buffer
arguments — compiled as Formatter(mode).format(template, …).
METHOD iterator() RETURNS ValueIterator[char32]reads
String concatenation. Returns a fresh String; both receivers
are unchanged.
ITERATOR — value-form (char32 is by-value). Wraps the bounded
walk in a sibling StringIterator class so the surface
matches the standard ValueIterator pipe-XOR shape (nextValue /
peekValue / skipValue). _ValueArray's raw iterator has a
different signature (no STATUS pipe-XOR), so the wrap is
necessary.