Skip to content

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.

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 String when every match fills it and Maybe<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} with n > 0 holds its last repetition and is String, 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, C is the anonymous struct of the groups: Regex`(?P<year>\d{4})-(?P<month>\d\d)?` is a Regex<{year: String, month: Maybe<String>}>.
  • Otherwise several groups are a tuple in order (Regex`(\d+)-(\w+)?` is a Regex<(String, Maybe<String>)>, and Regex"(a)|(b)" a Regex<(Maybe<String>, Maybe<String>)>), one group is its type alone, since Nomi has no one-element tuple (Regex`v(\d+)` is a Regex<String>), and a pattern with no group is a Regex<Unit>, whose String.captures is Some(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<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)
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")])
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+"

impl Matcher for Regex<C>

fn is_contained_in(re: Regex<C>, text: String) -> Bool

impl Matcher.is_contained_in

True if the regex matches anywhere in text.

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.

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.

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.

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 $.

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.

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.

impl Literal for Regex<C>

fn from_fragments(fragments: List<Fragment<String>>) -> Result<Regex<List<Maybe<String>>>, String>

impl Literal.from_fragments

impl Display for Regex<C>

fn to_string(re: Regex<C>) -> String

impl Display.to_string

The source pattern.

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\""