Regex

A compiled regular expression.

Constructor

`Regex pattern`

Compiles a regular expression pattern.

Parameters

Name	Type	Description
`pattern`	`Str`	RE2-compatible pattern.

Errors

ValueError if the pattern is invalid.

Example

let digits = Regex r"\d+"
let date = Regex r"(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})"

Methods

`find haystack -> Iter[Captures]`

Returns an iterator over all non-overlapping matches in haystack.

Parameters

Name	Type	Description
`haystack`	`Str`	String to search in.

Example

let pattern = Regex r"\d+"
for caps = pattern.find "one 1 two 2 three 3"
  echo $caps  # => 1, then 2, then 3

# Collect all matches into an array
let matches = [...pattern.find "1 22 333"]
echo $matches.len  # => 3

Open in playground

`match haystack -> (Captures | nil)`

Searches for the first match anywhere in haystack.

Parameters

Name	Type	Description
`haystack`	`Str`	String to search in.

Example

let pattern = Regex r"\d+"
let caps = pattern.match "abc 42 def"
echo $caps  # => 42

let no_match = pattern.match "no digits"
echo $no_match  # => nil

Open in playground

`replace haystack replacement … -> Str`

Replaces matches of this pattern in haystack.

Parameters

Name	Type	Description
`haystack`	`Str`	String to search in.
`replacement`	`(Str \| std.Fmt \| Func)`	Literal text, replacement template, or callback.
`:limit?`	`Int`	How many matches to replace. Replaces all matches when omitted.

`replacement`

A Fmt template fills holes from each match:

$#1, $#2, … — numbered capture groups
$#name — named capture groups

Use the braced form, such as ${#1:>8}, for formatting specifications. A plain Str is inserted literally, including any $ characters. A callback receives a Captures for each match and must return a Str.

`:limit`

limit: N (positive) — replace at most N matches.
limit: 0 — replace nothing, returning haystack unchanged.

Negative limits are not supported.

Example

let re = Regex r"(\w+)@(\w+)"
echo $ re.replace "a@b c@d" t"$#2=$#1"  # => b=a d=c

# Named groups
let date_re = Regex r"(?<m>\d{2})/(?<d>\d{2})/(?<y>\d{4})"
echo $ date_re.replace "03/22/2026" t"$#y-$#m-$#d"  # => 2026-03-22

# With limit
let comma = Regex r","
echo $ comma.replace "a,b,c,d" ";" limit: 2  # => a;b;c,d

# Callback replacement
let upper = Regex r"[a-z]+"
echo $ upper.replace "hello world" do |caps|
  str(caps[0]).upper()
# => HELLO WORLD

Errors

Exception	Condition
`MissingPosError`	A numbered capture hole cannot be filled
`MissingKeyError`	A named capture hole cannot be filled

`rsplit haystack … -> Iter[Str]`

Splits haystack around matches, yielding segments right to left.

Like split, but the rightmost segment comes first. rsplit always buffers all matches internally, since the regex engine only scans forward.

Parameters

Name	Type	Description
`haystack`	`Str`	String to split.
`:limit?`	`Int`	How many splits to perform, and from which end. Splits fully when omitted.

`:limit`

limit: N (positive) — split at most N times from the right; the last element yielded is the unsplit left remainder.
limit: -N (negative) — split at most N times from the left, but still yield segments right to left.

Example

let comma = Regex r","
assert_eq [...comma.rsplit "a,b,c"] ["c", "b", "a"]

# Positive limit: 1 split from the right
assert_eq [...comma.rsplit "a,b,c" limit: 1] ["c", "a,b"]

# Negative limit: 1 split from the left
assert_eq [...comma.rsplit "a,b,c" limit: -1] ["b,c", "a"]

`split haystack … -> Iter[Str]`

Splits haystack around matches of this pattern.

Returns an iterator that yields the Str substrings between matches. Iteration is lazy where possible; a negative limit requires buffering all matches up front.

Parameters

Name	Type	Description
`haystack`	`Str`	String to split.
`:limit?`	`Int`	How many splits to perform, and from which end. Splits fully when omitted.

`:limit`

limit: N (positive) — split at most N times from the left; the last element is the unsplit remainder.
limit: -N (negative) — split at most N times from the right, but still yield segments left to right. Useful for splitting off a known-length suffix.

Example

let ws = Regex r"\s+"
assert_eq [...ws.split "hello  world  foo"] ["hello", "world", "foo"]

# Positive limit: 1 split from the left
assert_eq [...ws.split "a b c" limit: 1] ["a", "b c"]

# Negative limit: 1 split from the right
let head tail = ws.split "a b c" limit: -1
assert_eq $head "a b"
assert_eq $tail "c"

# Destructuring
let first ...rest = ws.split "a b c d"
assert_eq $first "a"
assert_eq [...rest] ["b", "c", "d"]

Open in playground