std.regex

Regex.compile evaluates its pattern string once and returns Ok containing an immutable compiled pattern. Malformed or unsupported syntax returns Err containing a nonempty explanatory string. Compile errors are data and do not issue a diagnostic. Error wording has no fixed spelling.

Patterns match Unicode scalar values without Unicode normalization. Ordinary characters match themselves. Dot matches any scalar except a line feed. Concatenation, ordered alternation with a vertical bar, capturing groups, and noncapturing groups are supported. The empty pattern and empty alternatives are valid.

Character classes support literal members, inclusive scalar ranges, and a leading caret for negation. An inverted range is invalid. Escape a metacharacter with a backslash to match it literally. The escapes for n, r, and t match line feed, carriage return, and tab.

The quantifiers *, +, and ? mean zero or more, one or more, and zero or one. Counted forms {m}, {m,}, and {m,n} use nonnegative decimal counts with m no greater than n. A following question mark makes a repetition lazy. Unescaped braces outside classes delimit a repetition. Quantifiers require an atom and cannot directly repeat an anchor. Possessive quantifiers are invalid.

A caret and dollar anchor the beginning and end of the input. The escapes \A and \z keep those whole-input meanings. Inline flags i, m, and s select Unicode simple case folding, line anchors, and dot matching line feeds. The forms (?flags) and (?flags:pattern) set flags for the remaining group or a nested group. A minus sign clears subsequent flags.

Case folding uses the C and S mappings in Unicode 16.0 CaseFolding.txt and excludes the locale-specific T mappings and multiscalar F mappings. The m flag also permits a caret after a line feed and a dollar before a line feed. It does not remove a carriage return before that line feed.

Unicode properties use Unicode 16.0. The class \d is Decimal_Number. The class \s is White_Space. The class \w combines Alphabetic, Mark, Decimal_Number, Connector_Punctuation, and Join_Control. Uppercase D, S, and W negate those classes. The escapes \b and \B test a boundary or nonboundary between word and nonword scalars. Missing text at either end is nonword.

The forms \p{name} and \P{name} match or negate a Unicode general category, script, or binary property. Use a category alias, a binary-property alias, or Script= followed by a script alias. Names use Unicode 16.0 aliases and ignore case, spaces, and underscores. An unknown property or value is invalid. Unicode matching cannot be disabled to match a partial UTF-8 sequence.

Named captures use (?<name>pattern). Names are case sensitive unique ASCII identifiers beginning with a letter or underscore and continuing with letters, digits, or underscores. The alternative spelling (?P<name>pattern) is invalid.

Backreferences, lookaround, conditionals, atomic groups, and unknown alphanumeric escapes are invalid. Compile performs no I/O and never changes the pattern string.

Regex.isMatch reports whether a match exists anywhere in the input. Regex.find returns Some containing the first match or None() when no match exists. Regex.findAll returns every nonoverlapping match in search order and returns an empty array when no match exists.

Search begins at the earliest Unicode scalar boundary that permits the complete pattern to match. At that position alternatives are tried in pattern order. Greedy repetitions prefer more scalars and lazy repetitions prefer fewer scalars while still allowing the rest of the pattern to match.

After a nonempty match, findAll resumes at its exclusive end. After an empty match, it resumes at the next Unicode scalar boundary. An empty match directly at the end of the preceding nonempty match is skipped and search advances to the next scalar boundary.

An empty pattern visits every scalar boundary, including both ends. The empty input has one boundary and produces one empty match for an empty pattern. Matching never splits the UTF-8 bytes of a scalar.

Regex.split and Regex.replaceAll use the same ordered match sequence as findAll. Repeated calls start a new search and do not retain a cursor. The input string and compiled pattern are unchanged.

The receiver is evaluated once before the positional arguments, which are evaluated once from left to right. Search does not invoke user callbacks or access external state. No match is an ordinary result and does not produce a diagnostic.

Match.start and Match.end are read-only nonnegative UTF-8 byte offsets in the original input. They follow the inclusive start and exclusive end of byte intervals →. Both are scalar boundaries and the end does not exceed the UTF-8 byte length of the input.

Match.text is the matched substring. An empty match has equal start and end and an empty text value. The offsets are not string grapheme indexes. A match may select a combining mark inside a grapheme.

Encoding the original input with encodeUtf8, slicing its bytes from start to end, and calling decodeUtf8 returns Ok containing Match.text. This relationship also holds for non-ASCII input.

Match.groups returns an independent array indexed by capture number. Entry zero is Some containing the entire match. Capturing parentheses are numbered from one in opening-parenthesis order. Named groups participate in the same numbering and noncapturing groups do not.

A nonparticipating capture has value None(). A participating empty capture has value Some containing an empty string. A repeated capture retains the last participating capture in the selected match.

Match.named returns an independent map from capture names to captured strings. A nonparticipating named capture is absent. A participating empty named capture is present with an empty string. Names are inserted in ascending ASCII order.

Reading a Match field evaluates its receiver once and does not modify the Match or input. Mutating a groups array or named map does not affect a later field read. Field access cannot fail for a Match value.

Regex.split returns the input portions between the matches selected by findAll. Delimiters disappear and capture groups are not inserted. Empty portions at either end and between adjacent delimiters are retained. No match produces an array containing the original input.

Regex.replaceAll replaces the same nonoverlapping matches while copying all text between them unchanged. No match returns the original text. The operation does not search inserted replacement text.

Replacement references use a dollar sign followed by a braced capture number or name. Capture zero denotes the complete match. An unknown or nonparticipating capture expands to an empty string. Two dollar signs produce one literal dollar.

A replacement selector is a nonnegative decimal capture number or an ASCII capture name. Dollar text that is neither a double dollar nor a well-formed braced selector is literal. Unbraced dollar names and numbers do not form references. Expansion is performed once and captured dollar text is not expanded again.

An empty pattern splits at every scalar boundary and inserts replacement text at those same boundaries. The adjacent-empty-match rule from findAll also applies when a nonempty match is followed by an empty candidate.

The receiver is evaluated once before text and replacement arguments, which are evaluated once from left to right. Splitting and replacement leave the original string and Regex unchanged. They have no external effects and do not call a user callback.