`std/regex/regex`

std/regex/src/regex.trb

Regex and RegexMatch: a compiled pattern as a value, and what one match found.

type Regex

type Regex with Show, Equals, TryFrom<String, RegexError>

A regular expression with the syntax and the semantics of RE2: it matches in time linear in the length of the text, so it has no backreferences and no lookaround. It works on characters, not bytes, and every position it answers is a byte offset into the text, as every position of a String is.

Examples

const date: Regex = "(?P<year>\d{4})-(?P<month>\d{2})-(?P<day>\d{2})"
print date.matches("2026-09-25")
print date.find("due 2026-10-01")?.named("month")
print date.replace("2026-09-25", "$day.$month.$year")

fn tryFrom

static fn tryFrom(text: String): Result<Regex, RegexError>

The pattern text, compiled.

Errors

A RegexError with the byte offset of what is wrong: a syntax error, a backreference or a lookaround, a repetition above 1000, or a pattern that compiles to more than 100000 instructions.

fn text

fn text(): String

The pattern as it was written.

fn show

fn show(): String

Not documented.

fn equals

fn equals(other: Regex): Bool

Not documented.

fn groupCount

fn groupCount(): Int

How many capturing groups the pattern has, without the whole match.

fn groupNames

fn groupNames(): List<String?>

The names of the groups, by their index; the whole match (0) and an unnamed group have none.

fn matches

fn matches(text: String): Bool

Whether the whole text matches.

fn isFound

fn isFound(text: String): Bool

Whether the pattern matches anywhere in the text.

fn wholeMatch

fn wholeMatch(text: String): RegexMatch?

The match of the whole text, with its groups.

fn find

fn find(text: String): RegexMatch?

The first match in the text: the leftmost one, and of those the one the pattern prefers.

fn findFrom

fn findFrom(text: String, from: Int): RegexMatch?

The first match that starts at byte from or after it. ^ and \b still see the text before it.

fn findAll

fn findAll(text: String): List<RegexMatch>

Every match, left to right, none overlapping. An empty match right behind the previous one does not count.

fn replace

fn replace(text: String, replacement: String): String

The text with every match replaced by replacement, in which $1 and $\{1\} stand for a group by its index, $name and $\{name\} for a group by its name, and $$ for a $. A group that did not take part is empty.

fn replaceFirst

fn replaceFirst(text: String, replacement: String): String

The text with the first match replaced, as Regex.replace does it.

fn replaceWith

fn replaceWith(text: String, transform: (found: RegexMatch) => String): String

The text with every match replaced by what transform makes of it.

fn split

fn split(text: String): List<String>

The text cut apart at every match, which is dropped: ,\s* splits "a, b,c" into a, b and c. An empty match at the start does not make an empty first piece, and the rest of the text after the last match is the last piece.

extend String with From<Regex>

extend String with From<Regex>

A pattern is its text wherever a Regex is written or read: Encode and Decode go through this pair.

fn from

static fn from(value: Regex): String

type RegexMatch

type RegexMatch

One match: where it is in the text, and what each group found. Every position is a byte offset into the text.

Examples

const address: Regex = "(\w+)@(\w+)"
const found = address.find("mail ada@example")?
print "{found.text()} {found.group(1)} {found.start()}"

fn start

fn start(): Int

Where the match starts.

fn end

fn end(): Int

Where the match ends: the offset right after it.

fn text

fn text(): String

The text of the whole match.

fn group

fn group(index: Int): String?

The text a group found, by its index - 0 is the whole match - or None where it took no part.

fn named

fn named(name: String): String?

The text a named group found, or None where it took no part or the pattern has no group of that name.

fn groupRange

fn groupRange(index: Int): GroupRange?

Where a group is, by its index, or None where it took no part.

fn groups

fn groups(): List<String?>

What every group found, the whole match first.

fn namedGroups

fn namedGroups(): Map<String, String>

The named groups that took part, by name.

fn decoded

fn decoded<Value: Decode>(): Result<Value, DecodeError>

The named groups read as a Value whose fields have their names: (?P<year>\d+)-(?P<month>\d+) becomes a type with the fields year and month. The texts are read as what each field asks for, and a group that took no part is a field that is absent, so its default applies.

fn expanded

fn expanded(replacement: String): String

replacement with its $ references replaced by the groups of this match.

type GroupRange

type GroupRange

Where a group of a match is: from start to right before end, as byte offsets.

field start

start: Int

Not documented.

field end

end: Int

Not documented.