Module string/string

Render self under spec. An unrecognised spec degrades to the plain to_string() rendering rather than failing.

Create a new empty string (zero allocation)

Create a new empty string with pre-allocated capacity for the given number of bytes. The string starts empty but can hold capacity bytes without reallocating.

Create a string from raw bytes WITHOUT checking that they are UTF-8.

This is the unchecked constructor: the caller guarantees validity, and nothing scans the buffer. Use it when the bytes came from something that already produced UTF-8 — another String, a UTF-8 encoder, a byte-exact slice taken at rune boundaries. For bytes of unknown provenance (a file, a socket, a subprocess) use from_utf8, which validates and reports where the input went wrong.

Create a string from raw bytes, checking that they are valid UTF-8.

The checked counterpart to from_bytes: Err(StringError.InvalidUtf8) carries a Utf8Error naming the defect and the byte offset it starts at. Validation is a single linear scan through std/encoding/utf8.

Create a string from a slice of bytes str The slice is a fat pointer containing data pointer and length Example: String.from(slice) where slice is str

Create a string from a C null-terminated string *(u8) Copies bytes until it finds a null byte (0) Example: String.from_cstr(c_string_ptr)

Note: We manually search for the null terminator by iterating

Convert the string to a null-terminated C string. Returns an ArrayList(u8) with the string bytes followed by a \0.

Number of BYTES in this string's UTF-8 encoding — O(1).

BYTE basis. This is the unit every index-taking method on String speaks: at, substring, the s(a..b) / s(a..=b) slice sugar, index_of, last_index_of, contains(from_index), starts_with(position), ends_with(end_position) and the Pattern trait. It agrees with str.len(), StringBuilder.len(), Index(usize) (which yields a u8) and Rust's str::len().

For "how many runes" use chars().count() (O(n)); to walk runes together with the byte offset each one starts at, use char_indices(). (plans/archive/STD_API_AUDIT_D4_PLAN.md D4 PR 3 — this returned a RUNE count before that flip.)

Check if the string is empty

Get a reference to the internal byte array Returns an empty ArrayList if the string is empty

Get a str view into the string's UTF-8 bytes Returns a fat pointer (pointer + length) without copying PRIVILEGED raw view of the heap buffer (ptr + byte length) for C interop and pragma'd std internals. Naming RawSlice requires pragma(Pragma.AllowUnsafe); the view dangles if the String mutates or dies — callers must not let it escape the borrow site. (This replaces the deleted as_str(): heap bytes can no longer be viewed as str, which is the STATIC string view. See plans/archive/SLICE_REWORK.md.)

Decode a UTF-8 encoded rune starting at the given byte index Internal helper method

True when byte offset index sits on a rune boundary.

0 and len() are always boundaries; an index past the end never is. Mirrors Rust's str::is_char_boundary. (Defined here, beside at and substring, because an impl block cannot call forward into a later one and both of those need it.)

Decode the rune that STARTS at byte offset index.

BYTE basis (plans/archive/STD_API_AUDIT_D4_PLAN.md D4 PR 3 — this took a rune index before the flip). .None is returned for the three ways a byte offset can fail to name a rune: at or past len(), inside a rune (a UTF-8 continuation byte), or on bytes that do not decode.

while(i < s.len(), { s.at(i) }) therefore visits continuation bytes and yields .None at each of them — use char_indices() (or chars()) to walk runes.

Concatenate two strings (like JavaScript +)

Append another String to this string in-place (mutates self).

Append a str slice to this string in-place (mutates self).

Append a single byte to this string in-place (mutates self). The caller must ensure the byte maintains valid UTF-8.

Append one rune, UTF-8 encoded — Rust's String::push.

push_byte appends a single BYTE and will happily build invalid UTF-8; this is the rune-level counterpart, so it is what you want for anything outside ASCII.

Reserve capacity for at least additional more bytes. If the string is empty, creates a new buffer with the given capacity.

Clear the string content but keep the allocated buffer for reuse.

Get the byte at the given index. Panics if the index is out of bounds (mirrors str's byte indexing). Use len() for the valid range and bytes() for sequential iteration.

Owned copy of the BYTES in [r.start, r.end) — s(a..b) lowers to this.

Same contract as substring, including the boundary policy: an endpoint inside a rune panics.

Inclusive-range companion (s(a..=b)) — BYTE offsets, r.end included.

Because r.end is the LAST byte kept, it must be the last byte of a rune for r.end + 1 to land on a boundary; otherwise this panics like substring.

Owned copy of the bytes in [start, end).

BYTE basis (plans/archive/STD_API_AUDIT_D4_PLAN.md D4 PR 3 — these were rune indices before the flip).

Boundary policy, in full:

• Out-of-range CLAMPS. start and end past len() are pulled back to len(), and start >= end yields the empty string. This is the forgiving behaviour substring has always had, and it is kept.
• A non-boundary index PANICS. An endpoint inside a rune is a programmer error — a byte offset that came from the wrong basis — not a range condition, and honouring it would hand back invalid UTF-8.
• try_substring(start, end) is the non-panicking form: it returns .None for a bad range instead of clamping or panicking.
• floor_char_boundary / ceil_char_boundary snap an arbitrary offset onto a boundary first, for callers doing byte arithmetic.
• Rune-indexed slicing has no method form — walk char_indices() for byte offsets and slice with those.

Byte offset of the first occurrence of substr at or after from_index.

BYTE basis, in AND out (plans/archive/STD_API_AUDIT_D4_PLAN.md D4 PR 3 — both were rune indices before the flip). from_index is a byte offset; the returned index is the byte offset the match starts at, so it can be fed straight back into substring.

from_index needs no boundary check and gets none: UTF-8 is self-synchronizing, so a valid-UTF-8 needle can never match starting at a continuation byte. Starting the scan mid-rune therefore cannot invent a match, and for a NON-EMPTY needle every index this returns is a rune boundary at or before len().

The empty needle is the one exception, and it is deliberate. It matches everywhere, so index_of(``, i) answers .Some(i) verbatim — including an i inside a rune and an i past len() (JavaScript's indexOf("") clamps to the length; this does not, and neither did the pre-D4 rune-indexed version). An offset past the end is harmless downstream because substring clamps, but a MID-RUNE one is not: substring panics there. Callers that feed a search result straight back into a slice and can be handed an empty needle should go through try_substring, or snap with floor_char_boundary. Not called directly — go through index_of.

Private: is substr present at or after BYTE offset from_index?

BYTE basis for from_index (plans/archive/STD_API_AUDIT_D4_PLAN.md D4 PR 3 — it was a rune index before the flip). Not called directly — go through contains.

Split the string by a separator into an array of strings (like JavaScript split) Returns an ArrayList of String

Byte offset of the LAST occurrence of substr starting at or before from_index.

BYTE basis, in AND out (plans/archive/STD_API_AUDIT_D4_PLAN.md D4 PR 3 — both were rune indices before the flip). from_index is the highest byte offset a match is allowed to START at; the default usize.MAX means "anywhere". The result is the byte offset of the match, and for a non-empty needle it is always a rune boundary.

The empty needle answers len() regardless of from_index (Rust's rfind("") shape), so it is the one case where the result can exceed the cap the caller asked for. That is the pre-D4 behaviour carried over unchanged — only the unit changed, from a rune count to a byte count. Not called directly — go through last_index_of.

Private: does this string have prefix starting at BYTE offset position?

BYTE basis (plans/archive/STD_API_AUDIT_D4_PLAN.md D4 PR 3). Before the flip position was walked rune-by-rune — and walked WRONG: the counter advanced on a lead byte while the loop also stepped one byte, so "你好".starts_with("好", 1) stopped at byte 1, in the middle of 你. That is §1.3(a) of the plan, and byte indexing removes the walk that caused it rather than repairing it.

position is never boundary-checked: a valid-UTF-8 prefix cannot match starting at a continuation byte, so a mid-rune position simply answers false. An empty prefix is present anywhere, including past the end.

The UTF-8-aware byte-compare reused by the Pattern impls behind the generic starts_with<P : Pattern> (see plans/backlog/OVERLOADING_REDESIGN.md §4). Not called directly — go through starts_with.

Private: does the first end_position BYTES of this string end with suffix?

BYTE basis (plans/archive/STD_API_AUDIT_D4_PLAN.md D4 PR 3 — end_position was a rune count before the flip). The default usize.MAX means "the whole string"; anything past len() clamps to it. Like _has_prefix, a mid-rune end_position needs no rejection: a valid-UTF-8 suffix cannot end there, so the answer is simply false.

Not called directly — go through ends_with.

Uppercase using the full Unicode 15.1 case mapping (all scripts, plus the one-to-many expansions such as ß → SS and fi → FI). Locale-independent (never consults the C locale). Context-sensitive rules (Greek final sigma, Turkish dotted i) are not applied — the mapping is per code point, like Go's strings.ToUpper. ASCII input keeps a byte-wise fast path.

Lowercase using the full Unicode 15.1 case mapping (all scripts, plus the İ → i̇ expansion). Locale-independent. ASCII input keeps a byte-wise fast path.

Uppercase ASCII letters A-Z only (byte-wise); all other bytes pass through unchanged. The explicitly-ASCII counterpart to to_uppercase for when the Unicode mapping must not apply (identifiers, protocol tokens, …).

Lowercase ASCII letters A-Z only (byte-wise); all other bytes pass through unchanged. The explicitly-ASCII counterpart to to_lowercase.

Helper to check if a byte is ASCII whitespace Space (0x20), Tab (0x09), Newline (0x0A), Carriage Return (0x0D), Form Feed (0x0C), Vertical Tab (0x0B)

Remove whitespace from both ends of the string (like JavaScript trim)

Remove whitespace from the start of the string (like JavaScript trimStart)

Remove whitespace from the end of the string (like JavaScript trimEnd)

BYTE offset in haystack to test the prefix at.

A rune match must END exactly at end_position (clamped to len()), so a mid-rune end_position can never match.

BYTE offset in haystack to start searching from.

BYTE offset in AND out: searches from byte from_index, answers with the byte offset of the match.

BYTE offset in AND out: the highest byte offset a match may start at, answering with the byte offset of the last such match.

Number of BYTES the match STARTING EXACTLY at byte offset at occupies — 0 when no match starts there. replace, replace_all, split_once and strip_prefix cut the haystack by it; a zero-width pattern (empty string, empty-matching regex) legitimately answers 0.

Every piece of haystack between occurrences of this pattern, in order. The only Pattern method with no offset argument — it always covers the whole haystack — and the only one an implementation may give a shape of its own: String / str treat an EMPTY pattern as "split into runes" (see String.split), which no offset-based method can express.

Does self have prefix starting at BYTE offset position (default 0)?

Does the first end_position BYTES of self end with suffix? end_position defaults to usize.MAX, meaning the whole string, and clamps to len().

Does substr occur at or after BYTE offset from_index (default 0)?

BYTE offset of the first occurrence of substr at or after BYTE offset from_index (default 0), or .None.

BYTE offset of the last occurrence of substr starting at or before BYTE offset from_index (default usize.MAX, meaning anywhere), or .None.

Split on runs of ASCII whitespace, discarding empty pieces — Rust's split_whitespace. Leading and trailing whitespace produce no empty entries, which is what separates this from split(" ").

Split on separator, at most n pieces — the final piece keeps the rest of the string, separators included. Rust's splitn. n == 0 yields nothing, as in Rust.

Whether every byte is ASCII (< 0x80) — Rust's is_ascii.

ASCII-case-insensitive equality — Rust's eq_ignore_ascii_case. Only A-Z/a-z fold; every other byte must match exactly, so this is a byte comparison and never allocates.

Shorten to new_len BYTES, panicking if that is not a char boundary — Rust's truncate. A longer new_len is a no-op.

self with every leading occurrence of pat removed — Rust's trim_start_matches. Repeats, so "aaab".trim_start_matches("a") is "b", unlike the single-shot strip_prefix.

A ZERO-WIDTH pattern (the empty string, a regex matching empty) strips nothing and terminates rather than spinning.

self with every trailing occurrence of pat removed — Rust's trim_end_matches. Repeats, and terminates on a zero-width pattern.

self with every leading AND trailing occurrence of pat removed — Rust's trim_matches.

self cut at every occurrence of separator — Rust's str::split, but EAGER: the pieces come back as an ArrayList(String), not a lazy iterator.

separator is any Pattern (a str, a String, a single rune, or a compiled Regex). Separators are consumed, so n matches yield n + 1 pieces, including empty ones at the ends; a separator that never matches yields self alone, and splitting the empty string yields one empty piece.

DIVERGENCE from Rust: an EMPTY separator means "split into runes" (JavaScript's "abc".split("")), so "abc".split("") is ["a", "b", "c"] — not Rust's ["", "a", "b", "c", ""]. It is pinned to the rune vocabulary on purpose: a byte-wise split would hand back fragments that are not valid UTF-8 now that len() counts bytes.

split's pieces from the RIGHT — Rust's rsplit.

The pieces are the same ones split produces; only the ORDER is reversed, so "a.b.c".rsplit(".") is ["c", "b", "a"]. (Rust's returns a lazy iterator; Yo's split already returns the whole list, so this reverses it.)

Insert s at BYTE index idx, shifting the rest right — Rust's insert_str.

PANICS when idx is past the end or is not a char boundary, as Rust does; len() is bytes, so an index into the middle of a multi-byte rune would otherwise produce invalid UTF-8.

Insert one rune at BYTE index idx — Rust's insert. Same panics as insert_str.

Remove and return the rune STARTING at byte index idx — Rust's remove.

PANICS when idx is out of bounds or not a char boundary.

Remove and return the LAST rune, or .None when empty — Rust's pop.

Split at the FIRST occurrence of separator: .Some((before; after)) with the separator itself removed, or .None when it never occurs. Rust's str::split_once. A zero-width separator (empty string pattern, regex matching empty) splits before the first rune.

self without prefix, or .None when self does not start with it. Rust's str::strip_prefix.

self without suffix, or .None when self does not end with it. Rust's str::strip_suffix. The LAST starting occurrence of the suffix is the one stripped (so "aaa".strip_suffix("aa") is .Some("a"), like Rust).

Shared left-to-right scanner behind replace, replacen and replace_first. When bounded is true it stops after limit replacements and copies the rest of the string verbatim; limit == 0 with bounded replaces nothing.

Replace EVERY occurrence of search_value with new_value (D10 — Rust's str::replace).

search_value is any Pattern — a str, a String, a single rune, or a compiled Regex. A zero-width match inserts new_value between every pair of runes and at both ends — Rust's "abc".replace("", "-") == "-a-b-c-" — by stepping one rune past each zero-width match so the scan always advances. Returns self unchanged when the pattern never matches.

NOTE this replaced only the FIRST occurrence before D10. Use replacen for a bounded count.

Replace the first count occurrences of search_value with new_value, leaving any later ones alone — Rust's str::replacen.

replacen(p, v, usize(1)) is the pre-D10 meaning of replace. count == 0 returns self unchanged.

Replace the FIRST occurrence of search_value with new_value.

DEPRECATED (D10), kept for one release: this is what replace used to mean. Write replacen(search_value, new_value, usize(1)) instead.

Replace EVERY occurrence of search_value with new_value.

DEPRECATED (D10), kept for one release: replace now means this. Rust spells it replace, with no replace_all on str.

Feed this value's identity into hasher.

Returns a rune iterator over the string's Unicode characters

Returns a byte iterator over the string's raw UTF-8 bytes

Consume the string and return a rune iterator (default iteration)

Iterate (byte_offset, rune) pairs — Rust's char_indices().

_0 is the byte offset the rune starts at, _1 is the rune. This is the replacement for the while(i < s.len()) { s.at(i) } shape, which now visits continuation bytes and hands back .None at each of them.

The largest byte offset <= index that sits on a rune boundary.

index is clamped to len() first, so the answer is always a boundary of THIS string. Pair it with ceil_char_boundary to widen or narrow a byte range onto boundaries before slicing.

The smallest byte offset >= index that sits on a rune boundary.

index at or past len() clamps to len(), which is a boundary, so this always terminates on a valid one.

Byte-range slice that REFUSES a bad range instead of guessing — Rust's s.get(start..end).

Same BYTE basis as substring, but REFUSING where substring clamps or panics: .None is returned for each of the three ranges a byte slice cannot honour — start > end, end past len(), or an endpoint inside a rune (which would produce invalid UTF-8). An empty but valid range yields .Some of the empty string.

Returns a line iterator over the string. Each call to next() yields the next line (without the trailing \n).

Example

s := `hello\nworld`;
iter := s.lines();
assert(iter.next() == .Some(`hello`), "first line");
assert(iter.next() == .Some(`world`), "second line");
assert(iter.next() == .None, "done");

Returns a new string containing n copies of self. Returns an empty string when n == 0 or self is empty.

Example

assert(`ab`.repeat(usize(3)) == `ababab`, "repeat");
assert(`x`.repeat(usize(0)) == ``, "repeat 0");

Join an ArrayList(String) with this string as separator. Returns an empty string when items is empty.

Example

items := ArrayList(String).new();
items.push(`a`);
items.push(`b`);
items.push(`c`);
result := `, `.join(items);
assert(result == `a, b, c`, "join");

Parse the string as a boolean. Returns .Some(true) for "true", .Some(false) for "false", .None for anything else.

DEPRECATED (D12), kept for one release: use s.parse(bool), which reports WHY the parse failed instead of collapsing every reason into .None.

Parse an f64 — Rust's f64::from_str grammar: optional sign, digits with optional fraction and exponent, or inf/infinity/nan (case-insensitive). Leading/trailing whitespace and hex floats are NOT accepted. .None when the string is not a valid number.

DEPRECATED (D12), kept for one release: use s.parse(f64), which reports WHY the parse failed instead of collapsing every reason into .None.

Parse an i64 in the given radix (2..=36, digits 0-9/a-z/A-Z) — Rust's i64::from_str_radix. An optional leading +/- is allowed; _ is not. .None on an empty digit run, any non-digit, a bad radix, or overflow.

DEPRECATED (D12), kept for one release: use s.parse(i64), which reports WHY the parse failed instead of collapsing every reason into .None.

Parse a u64 in the given radix (2..=36) — Rust's u64::from_str_radix. An optional leading + is allowed; - is not. .None on any non-digit, a bad radix, or overflow.

DEPRECATED (D12), kept for one release: use s.parse(u64), which reports WHY the parse failed instead of collapsing every reason into .None.

Parse the string as a signed 32-bit integer — Rust's i32::from_str. An optional leading +/- is allowed. .None on an empty digit run, any non-digit, or a value outside i32.

DEPRECATED (D12), kept for one release: use s.parse(i32), which reports WHY the parse failed instead of collapsing every reason into .None.

Parse the string as a signed 64-bit integer — Rust's i64::from_str. An optional leading +/- is allowed. .None on an empty digit run, any non-digit, or overflow (i64.MIN itself is accepted).

DEPRECATED (D12), kept for one release: use s.parse(i64), which reports WHY the parse failed instead of collapsing every reason into .None.

Parse the string as an unsigned 32-bit integer — Rust's u32::from_str. An optional leading + is allowed, - is not. .None on an empty digit run, any non-digit, or a value outside u32.

DEPRECATED (D12), kept for one release: use s.parse(u32), which reports WHY the parse failed instead of collapsing every reason into .None.

Parse the string as an unsigned 64-bit integer — Rust's u64::from_str. An optional leading + is allowed, - is not. .None on an empty digit run, any non-digit, or overflow.

DEPRECATED (D12), kept for one release: use s.parse(u64), which reports WHY the parse failed instead of collapsing every reason into .None.

Parse this string as a T — Rust's str::parse::<T>() (D12).

match(`42`.parse(i32), .Ok(v) => v, .Err(_) => i32(0));

The error is T's own, so a caller can tell an empty string from garbage from an out-of-range value. T is written out because it cannot be inferred from the arguments — only from the result, which Yo does not do.

Parse a signed integer in radix (2..=36) — Rust's i64::from_str_radix, reporting WHY it failed.

Parse an unsigned integer in radix (2..=36) — Rust's u64::from_str_radix, reporting WHY it failed.

The default value of the type.

Create an independent clone of self.

The empty collection collect starts from.

Add one element to a partially-built collection and return it.

Consume the string and return a rune iterator (default iteration)

Advance the iterator and return the next value, or None when exhausted.

Advance the iterator from the back and return the previous value, or None when the two ends have met.

Consume the string and return a rune iterator (default iteration)

Advance the iterator and return the next value, or None when exhausted.

Advance the iterator from the back and return the previous value, or None when the two ends have met.

Consume the string and return a rune iterator (default iteration)

Advance the iterator and return the next value, or None when exhausted.

Advance the iterator from the back and return the previous value, or None when the two ends have met.

Consume the string and return a rune iterator (default iteration)

Advance the iterator and return the next value, or None when exhausted.

Advance the iterator from the back and return the previous value, or None when the two ends have met.

Render self under spec. An unrecognised spec degrades to the plain to_string() rendering rather than failing.

Render self under spec. An unrecognised spec degrades to the plain to_string() rendering rather than failing.

Render self under spec. An unrecognised spec degrades to the plain to_string() rendering rather than failing.