envzn
0.8 · beta · not released

Library / Strings / Text / String

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

Cloneable contract — deep copy. Returns a fresh String whose .data is an independent code-point array with the same values.

METHOD length() RETURNS int64
reads

Code-point count. O(1).

METHOD size() RETURNS int64
reads

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

True iff the String has zero code points.

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 String. Raises IndexOutOfBoundsError if i is out of range — bounds check lives in _ValueArray<char32_t>::operator[].

METHOD equals(REFERENCE String other) RETURNS boolean
reads

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

Use the lexicographic comparision below

METHOD compareTo(REFERENCE String other) RETURNS int32
reads

Lexicographic code-point comparison. Returns -1 / 0 / +1 in the usual three-way-comparison sense.

METHOD hash() RETURNS uint64
reads

FNV-1a 64-bit hash over the code-point array. Satisfies the Hashable contract. Deterministic.

METHOD hash(uint64 seed) RETURNS uint64
reads

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

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

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

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

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

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

METHOD contains(REFERENCE String needle, boolean caseMatch) RETURNS boolean
reads
METHOD startsWith(REFERENCE String prefix) RETURNS boolean
reads

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

True iff this String ends with suffix. Same delegation as startsWith.

METHOD lastIndexOf(REFERENCE String needle) RETURNS | int64
reads

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 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 find_first_of(REFERENCE String set) RETURNS | int64
reads

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

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

ASCII uppercase fold. Code points >= 0x80 unchanged.

METHOD toLower() RETURNS String
reads

ASCII lowercase fold. Code points >= 0x80 unchanged.

METHOD trim() RETURNS String
reads

TRIM (ASCII WHITESPACE: space, tab, LF, CR, VT, FF) -----------

METHOD trimStart() RETURNS String
reads
METHOD trimEnd() RETURNS String
reads
METHOD format(FormatArgument args...) RETURNS String
reads

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

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.