Module regex/index

Compile pattern with the JavaScript-style flag string flags_str (any of g, i, m, s, u, y; an empty string for none). Reach for new(pattern) when there are no flags — which is most of the time.

Returns .Err(RegexError) for every malformed pattern or flag string — the variants are matchable, so a caller can report the exact fault and the byte offset it was found at.

Capture groups are not capped: the VM allocates 2 * (n_groups + 1) capture slots per NFA thread, bounded only by memory. Only the syntax is limited — \1–\9 backreferences and $1–$9 replacement references are single-digit, so groups past 9 are reachable by name ((?<x>…) / \k<x> / ${x}) or by RegexMatch.group(i).

The pattern text this Regex was compiled from, exactly as given — Rust's Regex::as_str. Useful in error messages and logs; it is the SOURCE, not a canonical form, so it round-trips through Regex.new but says nothing about the compiled program.

Compile pattern with no flags — Rust's Regex::new, and the constructor to reach for. new_with_flags is the two-argument form.

This name used to take the flag string as a second parameter, so every flagless call had to spell Regex.new(p, "") and a sibling compile(p) existed to avoid it. One name per shape, with the common shape getting the short name, removes both.

Quote s so every character the pattern grammar treats specially (\ ^ $ . | ? * + ( ) [ ] { }) matches literally: each is preceded by a backslash. Bytes that are already ordinary (alphanumerics, spaces, other punctuation) and non-ASCII UTF-8 sequences pass through untouched, so Regex.new(Regex.escape(s)).unwrap().is_match(s) and round-tripping a user string through a larger pattern are both safe.

The scan behind exec, generalized to a nonzero start offset — what the Pattern impl needs for index_in(haystack, from). Sticky: one anchored attempt at from_byte. Otherwise every rune boundary from from_byte on, with the same literal-prefix jump exec uses.

The first match in input, or .None — Rust's Regex::find.

Rust splits this into find (the span only) and captures (the span plus its groups) because the first is cheaper. Yo's RegexMatch always carries its groups — group(i), name(n) — so there is nothing for a second method to add, and the two collapse into this one.

Every non-overlapping match, collected — Rust's find_iter().collect(). find_iter is the lazy form and is what a for loop should use.

Lazy variant of find_all: returns a RegexMatchIter (an Iterator) yielding the same non-overlapping matches one at a time. Works with for m in re.find_iter(s) and with manual next() loops; see the type's doc for the advance rules.

True when input contains a match — Rust's Regex::is_match.

There is no search() -> Option(usize) companion any more: it returned the first match's byte offset, which is find(input)'s RegexMatch.index(), so it was a strictly-less-informative duplicate carrying a JavaScript name.

input with the FIRST match replaced — Rust's Regex::replace.

FIRST, not all. This is deliberate and it is the one asymmetry in the whole replace family: String.replace(re, rep) — the same regex reached through the Pattern trait — replaces EVERY match (D10), because that is what str::replace means, while Regex::replace / Regex::replace_all is the split Rust's regex crate draws. So

re.replace(`aaa`, `X`)        // "Xaa"  — this method
`aaa`.replace(re, `X`)        // "XXX"  — String.replace, D10
re.replace_all(`aaa`, `X`)    // "XXX"  — say it explicitly

Returns input unchanged when nothing matches. replacement is interpreted: $& is the whole match, $1–$9 are groups, ${name} is a named group, $` and $' are the text before and after the match, and $$ is a literal $. Use replace_with when the replacement has to be computed, or when the text must be inserted verbatim.

The g flag does NOT change this — the engine ignores g entirely; the method name is the only thing that decides one-or-all.

input with EVERY non-overlapping match replaced — Rust's Regex::replace_all, and the method to reach for when "replace" means all of them (replace here does the first only).

Matches come from find_all, so they are the same non-overlapping, left-to-right set, and a zero-width-matching pattern advances the way find_all advances rather than looping. replacement gets the same $ interpretation as replace. Returns input unchanged when nothing matches.

Builds the whole result in one pass over input, so it is O(input + output) rather than one string allocation per match.

replace with the replacement COMPUTED per match: f receives the RegexMatch (so group(i)/named_group(...) are available) and returns the text to splice in. The callback IS the interpretation layer — its output is inserted verbatim, with no $1 reference processing.

replace_all with the replacement computed per match by f — same non-overlapping-match walk as replace_all, same verbatim insertion rule as replace_with.

input cut at every non-overlapping match, JavaScript-style — and JavaScript-style is a real divergence from Rust worth reading twice.

Two things follow String.prototype.split(regexp) rather than Rust's Regex::split:

• Capture groups are INTERLEAVED into the result. After each piece, the text of every group the pattern declared is pushed too, so Regex.new("(-)").unwrap().split("a-b-c") is ["a", "-", "b", "-", "c"], not ["a", "b", "c"]. A pattern with no groups behaves as you would expect.
• A group that did not participate contributes the literal string "undefined", JavaScript's undefined rendered as text. So Regex.new(",(x)?").unwrap().split("a,b") is ["a", "undefined", "b"]. That is a magic string in a typed API and it is filed as issues/stddoc-str-regex-split-emits-the-literal-string-undefined.md; an ArrayList(Option(String)) or simply omitting non-participating groups would both be better, and both are breaking.

A pattern that never matches yields [input] — one piece, never an empty list. This is also the body behind String.split(re), so the Pattern dispatch inherits both behaviours.

BYTE offset in haystack to test the prefix at.

A match must END exactly at end_position (clamped to len()).

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

BYTE offset in haystack to start searching from.

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.

Compile pattern with no flags — Rust's Regex::new, and the constructor to reach for. new_with_flags is the two-argument form.

This name used to take the flag string as a second parameter, so every flagless call had to spell Regex.new(p, "") and a sibling compile(p) existed to avoid it. One name per shape, with the common shape getting the short name, removes both.

The matched text itself — the same bytes as input().substring(index(), end()), captured at match time.

Start position of the match as a byte offset into the input.

Basis change (D4, 2026-08-26): this used to be a character (rune) index; it is now a byte index, matching String's byte-indexed API. The offset is always on a UTF-8 character boundary (a valid pattern cannot match at a continuation byte), so it can be fed directly to String.substring / index_of on the input. Use input().substring(usize(0), m.index()).chars().count() if a rune count is really needed.

End position of the match as a byte offset into the input (exclusive — the offset of the first byte AFTER the match). Always on a UTF-8 character boundary, for the same reason as index(). span() is index() .. end().

The whole match as a byte range index() .. end() into the input.

The whole string the match was found in, not just the matched part. The match holds a reference to it, so the offsets index() / end() / span() / group_span() stay meaningful for as long as the match does.

The text of capture group idx, 1-based, with 0 meaning the whole match — the same numbering $1 and \1 use in patterns.

.None means EITHER that the group did not participate in this match (an unmatched (x)?, or an alternative that was not taken) OR that idx is past group_count(). The two are not distinguishable here; compare idx against group_count() first if that matters.

Capture group's byte range into the input (1-based, mirroring group(); group 0 is the full match's span()), or .None when the group did not participate in the match or the index is out of range. A participating group's range satisfies input().substring(r.start, r.end) == group(idx).unwrap().

The text of the group declared as (?<name>...), or .None when no group has that name OR the named group did not participate — the same conflation as group.

O(number of named groups): the name table is scanned linearly on every call, so a loop over many names over a long input is quadratic. Names are compared for exact equality, case-sensitively.

How many capture groups the PATTERN declared, not counting group 0 and not counting how many actually participated. So a non-participating group is still counted, and group(i) is a legal call for every 1 <= i <= group_count().

The first match in input, or .None — Rust's Regex::find.

Rust splits this into find (the span only) and captures (the span plus its groups) because the first is cheaper. Yo's RegexMatch always carries its groups — group(i), name(n) — so there is nothing for a second method to add, and the two collapse into this one.

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

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

The pattern text this Regex was compiled from, exactly as given — Rust's Regex::as_str. Useful in error messages and logs; it is the SOURCE, not a canonical form, so it round-trips through Regex.new but says nothing about the compiled program.