std::regex
Regular expressions in RE2 syntax, matched in time linear in the input.
Write a pattern as a backtick literal, such as Regex`\d+` , so its
backslashes need no escaping. A literal without slots has its pattern
compiled when the program is checked, so an invalid one is a compile
error and the literal is a Regex. A literal with a slot
(Regex"room ${word}") is compiled when it runs and is a Result of
one.
A Regex<C> names its capture groups: C is what String.captures
gives for a match, and a literal’s C comes from its pattern
(Capture types).
A Regex is a Matcher, so String’s search functions take one in place of
a plain string. Test for a match with String.contains(text, Regex`\d+`),
collect every match with String.find_all(text, re), and split around
matches with String.split(text, Regex`,\s*`). Find the first match with
String.find(text, re), and read its capture groups with
String.captures(text, re) (every match’s with String.captures_all).
Replace every match with String.replace(text, re, replacement), whose
replacement names a group as $1 or ${name}.
Import with import std::regex.
Exports
Section titled “Exports”Types
Capture types
Section titled “Capture types”Regex<C> carries the type of its capture groups: C is what
String.captures returns for a match, inside a Maybe, and what
String.captures_all lists. The groups are the pattern’s from group 1,
in the order the pattern opens them; the whole match is String.find’s
result, not a group. A Regex literal whose pattern is fixed text (one
with no ${...}, in any quotes) has C
computed from the pattern by the compiler, as Swift types
/(\d+)-(\w+)?/:
- A group is
Stringwhen every match fills it andMaybe<String>when a match can leave it out: it stands under?,*or a repetition whose minimum is 0, in one alternative of a|, or inside a group that can be left out. A group under+or{n,m}withn > 0holds its last repetition and isString, as is one that can match the empty text ((a*)takes part, empty, in every match). - When every group is named (
(?P<year>...)or(?<year>...)) with a name a field can have,Cis the anonymous struct of the groups:Regex`(?P<year>\d{4})-(?P<month>\d\d)?`is aRegex<{year: String, month: Maybe<String>}>. - Otherwise several groups are a tuple in order (
Regex`(\d+)-(\w+)?`is aRegex<(String, Maybe<String>)>, andRegex"(a)|(b)"aRegex<(Maybe<String>, Maybe<String>)>), one group is its type alone, since Nomi has no one-element tuple (Regex`v(\d+)`is aRegex<String>), and a pattern with no group is aRegex<Unit>, whoseString.capturesisSome(Unit)for a match.
A regex compiled while the program runs, by Regex.compile or by a
literal that interpolates, has groups no one knows before it runs, and is
a Regex<List<Maybe<String>>>: one entry per group, Some of the text
for a group that took part, even an empty one, and None for one that
did not, so String.captures("b", Regex.compile("(a)|(b)")?) is
Some([None, Some("b")]).
C is phantom: every Regex holds a compiled pattern and nothing of
C, so the functions that do not read groups (Regex.pattern,
String.contains, the Matcher search functions, Display and Debug)
take a Regex<C> for any C, and ordinary code never writes it. A
function of your own that takes any regex is generic in it:
fn first<C>(re: Regex<C>, text: String) -> Maybe<C>.
Annotating a binding of a literal names its type, as
digits: Regex<Unit> = Regex`\d+` .
type Regex
Section titled “type Regex”type Regex<C>
A compiled regular expression whose capture groups have the type C.
Matching is RE2’s, by Go’s regexp package: it never backtracks, so it
takes time linear in the input, and it has no lookaround or
backreferences. Write a pattern as a backtick literal, Regex`\d+`:
its backslashes need no escaping and the pattern is checked when the
program is compiled.
A Regex is a Matcher: test, find, collect and split with the String
functions. C is what String.captures gives for a match; a literal’s
comes from its pattern, so Regex`(\w+)@(\w+)?` is a
Regex<(String, Maybe<String>)>, and the functions that do not read
groups take a Regex of any C.
import std::unit.Unit
assert String.contains("order 66", Regex`\d+`)
assert String.contains("room", Regex`\d+`) == False
assert String.find_all("order 66, aisle 7", Regex`\d+`) == ["66", "7"]
assert String.find("order 66, aisle 7", Regex`\d+`) == Maybe.Some("66")
assert String.split("a, b,c", Regex`,\s*`) == ["a", "b", "c"]
assert String.captures("ann@home", Regex`(\w+)@(\w+)?`) == Maybe.Some(("ann", Maybe.Some("home")))
pair = Regex`(\w+)@(\w+)?`
assert String.captures("ann@", pair) == Maybe.Some(("ann", Maybe.None))
assert String.captures("none", pair) == Maybe.None
{year:, month:} = String.captures("2024-05", Regex`(?P<year>\d{4})-(?P<month>\d\d)`)!
assert year + month == "202405"
assert String.captures_all("a=1 b=2", Regex`(\w)=(\d)`) == [("a", "1"), ("b", "2")]
assert String.captures("aa", Regex"(a*)") == Maybe.Some("aa")
assert String.captures("x", Regex"x") == Maybe.Some(Unit)
digits: Regex<Unit> = Regex`\d+`
assert String.contains("a1", digits)
Regex.compile
Section titled “Regex.compile”fn compile(pattern: String) -> Result<Regex<List<Maybe<String>>>, String>
type function on Regex
Compiles a pattern into a Regex, or returns Err with the reason
the pattern is invalid. Its groups are known only once it runs, so
String.captures gives them as a list, one Maybe per group.
assert Regex.pattern(Regex.compile("a+")?) == "a+"
assert Err(_msg) = Regex.compile("(")
assert String.captures("b", Regex.compile("(a)|(b)")?) == Maybe.Some([Maybe.None, Maybe.Some("b")])
Regex.pattern
Section titled “Regex.pattern”fn pattern<C>(re: Regex<C>) -> String
type function on Regex
Returns the pattern the regex was compiled from.
assert Regex.pattern(Regex`\d+`) == "\\d+"
Regex.is_contained_in
Section titled “Regex.is_contained_in”impl Matcher for Regex<C>
fn is_contained_in(re: Regex<C>, text: String) -> Bool
True if the regex matches anywhere in text.
Regex.is_prefix_of
Section titled “Regex.is_prefix_of”impl Matcher for Regex<C>
fn is_prefix_of(re: Regex<C>, text: String) -> Bool
impl Matcher.is_prefix_of
True if a match starts at the beginning of text.
Regex.is_suffix_of
Section titled “Regex.is_suffix_of”impl Matcher for Regex<C>
fn is_suffix_of(re: Regex<C>, text: String) -> Bool
impl Matcher.is_suffix_of
True if a match ends at the end of text.
Regex.split_in
Section titled “Regex.split_in”impl Matcher for Regex<C>
fn split_in(re: Regex<C>, text: String) -> List<String>
impl Matcher.split_in
Splits around every non-overlapping match.
Regex.replace_in
Section titled “Regex.replace_in”impl Matcher for Regex<C>
fn replace_in(re: Regex<C>, text: String, replacement: String) -> String
impl Matcher.replace_in
Replaces every non-overlapping match with replacement, in which $1,
${1} and ${name} are capture groups and $$ is a literal $.
Regex.find_all_in
Section titled “Regex.find_all_in”impl Matcher for Regex<C>
fn find_all_in(re: Regex<C>, text: String) -> List<String>
impl Matcher.find_all_in
Every non-overlapping match, left to right.
Regex.find_in
Section titled “Regex.find_in”impl Matcher for Regex<C>
fn find_in(re: Regex<C>, text: String) -> Maybe<String>
impl Matcher.find_in
The leftmost match, which may be empty.
Regex.from_fragments
Section titled “Regex.from_fragments”impl Literal for Regex<C>
fn from_fragments(fragments: List<Fragment<String>>) -> Result<Regex<List<Maybe<String>>>, String>
Regex.to_string
Section titled “Regex.to_string”impl Display for Regex<C>
fn to_string(re: Regex<C>) -> String
impl Display.to_string
The source pattern.
Regex.inspect
Section titled “Regex.inspect”impl Debug for Regex<C>
fn inspect(re: Regex<C>) -> String
impl Debug.inspect
The typed literal that builds this regex, as String.to_typed_literal
writes it: in double quotes when the pattern needs no escape there,
and in backticks when it does, unless it holds a backtick.
assert Debug.inspect(Regex"a+") == "Regex\"a+\""
assert Debug.inspect(Regex`\d+`) == "Regex`\\d+`"
assert Debug.inspect(Regex.compile("a`b")?) == "Regex\"a`b\""