Salam
Online editor

Standard library · Text

regex

Searching and replacing with a pattern: finding a number, an email address or a date in text and pulling it apart.

import regex
On this page
  1. Types
  2. Functions

A regular expression is a small language for describing the shape of text; [0-9]+ means "one or more digits". With one you can ask whether text matches a pattern, find every place it matches, and pull pieces out or replace them.

Every function comes in two forms. The one that takes a Regex uses a pattern compiled in advance and is faster when you use it repeatedly. The one whose name ends in Str takes the pattern as text and compiles it each time; that is more convenient for a one-off.

Parentheses in a pattern make a "group", and (?P<name>...) makes a named one. Group zero is the whole match. In a replacement, $1 and $2 stand for the groups.

Types

MatchResult

struct MatchResult
The result of a search. Rather than reading the fields directly, the Group functions are usually simpler.
NameTypeDescription
okbool = falseTrue when a match was found.
startint = -1Where the match starts, in bytes.
stopint = -1Where the match ends, in bytes; that position is not part of it.
countint = 0The number of groups, not counting group zero.
textstr = ""The whole text that was searched, not only the part that matched. For the match itself use Group(m, 0).
patternstr = ""The pattern the search was made with.
gsint[]Where each group starts.
geint[]Where each group ends.
regex-Group.salam
import regex

func main:
    r := regex.Compile("(?P<year>[0-9]{4})-(?P<month>[0-9]{2})")
    m := regex.FindMatch(r, "date: 2025-09")
    println m.ok, m.start, m.stop, m.text
    println regex.GroupCount(m), regex.GroupOk(m, 1)
    println regex.Group(m, 0), regex.Group(m, 1), regex.Group(m, 2)
    println regex.GroupStart(m, 2), regex.GroupEnd(m, 2)
    println regex.GroupIndex(m, "month"), regex.GroupByName(m, "year")
    m2 := regex.FindMatchFrom(r, "2024-01 and 2025-02", 5)
    println regex.Group(m2, 0)
    println regex.Group(regex.FindMatchStr("b+", "aabbbc"), 0)
    println regex.FindSubmatch(r, "2025-09")
    println regex.FindSubmatchStr("(a)(b)", "xab")
end
Outputtrue 6 13 date: 2025-09 2 true 2025-09 2025 09 11 13 2 2025 2025-02 bbb ["2025-09", "2025", "09"] ["ab", "a", "b"]

Regex

struct Regex
A compiled pattern. Build one with Compile and use it many times.
NameTypeDescription
patternstr = ""The text of the pattern that was compiled.
regex-Compile.salam
import regex

func main:
    r := regex.Compile("[0-9]+")
    println r.pattern, regex.IsValid("[0-9]+"), regex.IsValid("[0-9")
    println regex.Match(r, "abc123"), regex.Find(r, "abc123")
    println regex.Replace(r, "a1 b22 c333", "#")
    println regex.ReplaceAll(r, "a1 b22 c333", "#")
    println regex.MatchStr("^[a-z]+$", "salam"), regex.FindStr("o", "salam donya")
    println regex.ReplaceStr("a", "banana", "o"), regex.ReplaceAllStr("a", "banana", "o")
end
Output[0-9]+ true false true 3 a# b22 c333 a# b# c# true 7 bonana bonono

Functions

FindMatch

func FindMatch(re: Regex, text: str): MatchResult
Finds the first place the pattern matches and returns everything about it, groups included.

The example for this item is shown with the ones above: regex-Group.salam

FindMatchStr

func FindMatchStr(pattern: str, text: str): MatchResult
Like FindMatch, with the pattern as text.

The example for this item is shown with the ones above: regex-Group.salam

FindMatchFrom

func FindMatchFrom(re: Regex, text: str, from: int): MatchResult
Like FindMatch, but starts the search at byte from, for finding the next occurrence.

The example for this item is shown with the ones above: regex-Group.salam

GroupCount

func GroupCount(m: MatchResult): int
Returns the number of groups in the pattern, not counting group zero.

The example for this item is shown with the ones above: regex-Group.salam

GroupOk

func GroupOk(m: MatchResult, i: int): bool
True when group number i took part in this match. An optional group may stay empty.

The example for this item is shown with the ones above: regex-Group.salam

Group

func Group(m: MatchResult, i: int): str
Returns the text of group number i; group zero is the whole match.

The example for this item is shown with the ones above: regex-Group.salam

GroupStart

func GroupStart(m: MatchResult, i: int): int
Where the group starts, in bytes.

The example for this item is shown with the ones above: regex-Group.salam

GroupEnd

func GroupEnd(m: MatchResult, i: int): int
Where the group ends, in bytes.

The example for this item is shown with the ones above: regex-Group.salam

GroupIndex

func GroupIndex(m: MatchResult, name: str): int
Returns the number of a named group.

The example for this item is shown with the ones above: regex-Group.salam

GroupByName

func GroupByName(m: MatchResult, name: str): str
Returns the text of a named group.

The example for this item is shown with the ones above: regex-Group.salam

FindSubmatch

func FindSubmatch(re: Regex, text: str): Vector<str>
Returns the match and all its groups in a vector; element zero is the whole match.

The example for this item is shown with the ones above: regex-Group.salam

FindSubmatchStr

func FindSubmatchStr(pattern: str, text: str): Vector<str>
Like FindSubmatch, with the pattern as text.

The example for this item is shown with the ones above: regex-Group.salam

FindAllMatches

func FindAllMatches(re: Regex, text: str, limit: int): Vector<MatchResult>
Returns every match with its details. A limit of minus one means no limit.
regex-FindAll.salam
import regex

func main:
    r := regex.Compile("[0-9]+")
    text := "year 1403, month 7, day 12"
    println regex.FindAll(r, text)
    println regex.FindAllN(r, text, 2)
    println regex.FindAllStr("[a-z]+", "one two three")
    println regex.Split(regex.Compile(" *, *"), "a , b,c ,  d")
    println regex.SplitN(regex.Compile(","), "a,b,c,d", 2)
    println regex.SplitStr("-+", "2025--09---29")
    all := regex.FindAllMatches(r, text, -1)
    each m in all:
        println regex.Group(m, 0), m.start, m.stop
    end
end
Output["1403", "7", "12"] ["1403", "7"] ["one", "two", "three"] ["a", "b", "c", "d"] ["a", "b,c,d"] ["2025", "09", "29"] 1403 5 9 7 17 18 12 24 26

FindAllN

func FindAllN(re: Regex, text: str, limit: int): Vector<str>
Returns the text of at most limit matches.

The example for this item is shown with the ones above: regex-FindAll.salam

FindAll

func FindAll(re: Regex, text: str): Vector<str>
Returns the text of every match in a vector.

The example for this item is shown with the ones above: regex-FindAll.salam

FindAllStr

func FindAllStr(pattern: str, text: str): Vector<str>
Like FindAll, with the pattern as text.

The example for this item is shown with the ones above: regex-FindAll.salam

SplitN

func SplitN(re: Regex, text: str, limit: int): Vector<str>
Splits the text wherever the pattern matches, into at most limit pieces; the last piece is the rest of the text.

The example for this item is shown with the ones above: regex-FindAll.salam

Split

func Split(re: Regex, text: str): Vector<str>
Splits the text wherever the pattern matches. For separators with varying space around them it is more flexible than str.Split.

The example for this item is shown with the ones above: regex-FindAll.salam

SplitStr

func SplitStr(pattern: str, text: str): Vector<str>
Like Split, with the pattern as text.

The example for this item is shown with the ones above: regex-FindAll.salam

Expand

func Expand(m: MatchResult, template: str): str
Fills a template from the groups of a match; $1, $2 and so on stand for the groups.
regex-Expand.salam
import regex

func main:
    r := regex.Compile("([a-z]+)@([a-z]+)")
    text := "ali@home, sara@work"
    m := regex.FindMatch(r, text)
    println regex.Expand(m, "$2 <- $1")
    println regex.ReplaceExpand(r, text, "$2:$1")
    println regex.ReplaceAllExpand(r, text, "$2:$1")
    println regex.ReplaceExpandStr("(\\w+) (\\w+)", "hello world", "$2 $1")
    println regex.ReplaceAllExpandStr("(a)(b)", "abab", "$2$1")
end
Outputhome <- ali home:ali, sara@work home:ali, work:sara world hello baba

ReplaceExpand

func ReplaceExpand(re: Regex, text: str, template: str): str
Replaces the first match with the template, in which you can use $1 and the rest.

The example for this item is shown with the ones above: regex-Expand.salam

ReplaceAllExpand

func ReplaceAllExpand(re: Regex, text: str, template: str): str
Replaces every match with the template.

The example for this item is shown with the ones above: regex-Expand.salam

ReplaceExpandStr

func ReplaceExpandStr(pattern: str, text: str, template: str): str
Like ReplaceExpand, with the pattern as text.

The example for this item is shown with the ones above: regex-Expand.salam

ReplaceAllExpandStr

func ReplaceAllExpandStr(pattern: str, text: str, template: str): str
Like ReplaceAllExpand, with the pattern as text.

The example for this item is shown with the ones above: regex-Expand.salam

Compile

func Compile(pattern: str): Regex
Compiles a pattern. If the pattern might be wrong, because it came from a user for instance, check it with IsValid first.

The example for this item is shown with the ones above: regex-Compile.salam

IsValid

func IsValid(pattern: str): bool
True when the pattern is well formed.

The example for this item is shown with the ones above: regex-Compile.salam

Match

func Match(re: Regex, text: str): bool
True when the pattern matches anywhere in the text. To match the whole text, anchor the pattern with ^ and $.

The example for this item is shown with the ones above: regex-Compile.salam

Find

func Find(re: Regex, text: str): int
Returns where the first match starts, in bytes, or minus one.

The example for this item is shown with the ones above: regex-Compile.salam

Replace

func Replace(re: Regex, text: str, replacement: str): str
Replaces only the first match with new text.

The example for this item is shown with the ones above: regex-Compile.salam

ReplaceAll

func ReplaceAll(re: Regex, text: str, replacement: str): str
Replaces every match with new text.

The example for this item is shown with the ones above: regex-Compile.salam

MatchStr

func MatchStr(pattern: str, text: str): bool
Like Match, with the pattern as text.

The example for this item is shown with the ones above: regex-Compile.salam

FindStr

func FindStr(pattern: str, text: str): int
Like Find, with the pattern as text.

The example for this item is shown with the ones above: regex-Compile.salam

ReplaceStr

func ReplaceStr(pattern: str, text: str, replacement: str): str
Like Replace, with the pattern as text.

The example for this item is shown with the ones above: regex-Compile.salam

ReplaceAllStr

func ReplaceAllStr(pattern: str, text: str, replacement: str): str
Like ReplaceAll, with the pattern as text.

The example for this item is shown with the ones above: regex-Compile.salam