regex API

pub struct Group { text: text?, start: integer, end: integer }

One capture group of a match. text is null when the group did not take part (an alternation branch not taken, an optional group that matched nothing); start and end are then -1.

pub struct Match { text: text, start: integer, end: integer, groups: vector<Group>, names: vector<text> }

A match of a pattern in a subject: the matched text, its byte span, and its groups in pattern order (group 1 first — text IS group 0). names holds one entry per group, "" for an unnamed one, so named is a lookup.

pub fn group(self: Match?, i: integer) -> text?

Group i of the match (1-based, group(0) is the whole match), or null when it did not take part, there is no such group, or there was no match: the receiver is nullable so line.capture(p).group(1) reads in one go, a miss answering null all the way down.

pub fn named(self: Match?, name: text) -> text?

The group called name, or null when the pattern has no such name, the group did not take part, or there was no match.

pub fn search(self: text, pattern: text) -> integer?

Byte offset of the first match of pattern in the text, or null when there is no match (or the pattern is invalid). The conventional regex-search verb — named search, not find, because bare find on text is the stdlib's literal substring search. Call as line.search("[0-9]+").

pub fn matches(self: text, pattern: text) -> boolean

True if pattern matches anywhere in the text. self registers this as BOTH a method (line.matches(p)) and a free function (matches(line, p)). Collision-free on text (the stdlib has contains, not matches).

pub fn capture(self: text, pattern: text) -> Match?

The first match of pattern in the text with its capture groups, or null when there is none (or the pattern is invalid). Call as m = line.capture("^(\\w+)=(.+)$"); if m != null { key = m.group(1)?; }

pub fn capture_all(self: text, pattern: text) -> vector<Match>

Every non-overlapping match of pattern in the text, in order, each with its groups; empty when there is none. An empty match advances one character, so a* on "baa" answers three matches: "", "aa", "".

pub fn replace_on(self: text, pattern: text, template: text, limit: integer = 0) -> text

The text with its matches of pattern replaced by template, in which $1 / ${name} stand for a group, $0 for the whole match and $$ for a dollar. limit bounds how many matches are replaced, from the left; 0 (the default) replaces every one. Named replace_on beside split_on: bare replace on text is the stdlib's literal replace.

pub fn split_on(self: text, pattern: text) -> iterator<text>

Split the text on matches of pattern, yielding each piece lazily through an iterator<text> (reuses loft's coroutine channel — nothing is materialised). Named split_on, not split, because bare split on text is the stdlib character-separator split. Call as for piece in line.split_on("[,;]") { }.