Skip to content

RegExp

Defined in regexp@2.0.0

Simple regular expression.

Currently it only supports patterns below: - Character classes: [xyz], [^xyz], ., \d, \D, \w, \W, \s, \S - Character escapes: \t, \r, \n, \v, \f, [\b], \0, \cX, \xhh, \uhhhh, the octal escapes such as \012 (outside a bracket expression, those beginning with \0), and a backslash before any other character, which stands for that character. \c followed by no letter (in a bracket expression, no letter, digit or _) stands for the backslash alone. - Alternatives: x|y - Assertions: ^, $ - Groups: (x) - Quantifiers: x*, x+, x?, x{n}, x{n,}, x{n,m}, and x*?, x+?, x??, x{n}?, x{n,}?, x{n,m}?, which take as few rounds as they can

Outside a bracket expression, \b, \B and \1..\9 are reported as errors. JavaScript reads them as word boundary assertions and backreferences, or \1..\9 as octal escapes and digits where the pattern has fewer groups.

A search finds the match JavaScript finds: the one beginning leftmost, and among those beginning there, the first JavaScript reaches, trying alternatives from the left and taking as many rounds of a quantifier as it can, or as few for one followed by ?. a|ab matched against ab gives a. What each group captured is what JavaScript reports, too.

For what the pattern syntax above means, see mdn web docs: Regular expressions.

This module is the whole interface of the library, and its version number follows this module alone. The modules under RegExp._Internal are the parts the library is built from, and any version may change them.

LIMITATION:

A character class, . included, matches one byte, so it holds the single byte characters (U+0001..U+007F). UTF-8 writes a character from U+0080 upward as two or more bytes, and a Fix string holds no null character (U+0000). A character from U+0080 upward in a bracket expression, written as itself or as an escape, is reported as an error.

JavaScript reads a character from U+10000 upward as two UTF-16 code units, which bytes cannot stand for one at a time. \uhhhh for one of the two (U+D800..U+DFFF), and a quantifier after a character from U+10000 upward, are reported as errors.

Values

namespace RegExp::Matcher

find_all

Type: Std::String -> RegExp::Matcher -> (Std::Array (Std::Array (Std::I64, Std::I64)), RegExp::Matcher)

matcher.find_all(target) finds every match in target, and reports the scanner as the search left it.

What it reports is what RegExp::find_all reports, all the matches at once. To take the matches one at a time, use RegExp::find_all.

Parameters
  • target - The string to search.
  • matcher - The regular expression and its scanner.

find_all_in_bytes

Type: Std::Array Std::U8 -> RegExp::Matcher -> (Std::Array (Std::Array (Std::I64, Std::I64)), RegExp::Matcher)

matcher.find_all_in_bytes(bytes) is find_all over an array of bytes.

Parameters
  • bytes - The bytes to search.
  • matcher - The regular expression and its scanner.

find_from

Type: Std::I64 -> Std::String -> RegExp::Matcher -> (Std::Option (Std::Array (Std::I64, Std::I64)), RegExp::Matcher)

matcher.find_from(from, target) finds the match in target that begins first at or after the byte position from, and reports the scanner as the search left it.

What it reports is what RegExp::find_from reports.

Parameters
  • from - The byte position the match has to begin at or after.
  • target - The string to search.
  • matcher - The regular expression and its scanner.

find_from_in_bytes

Type: Std::I64 -> Std::Array Std::U8 -> RegExp::Matcher -> (Std::Option (Std::Array (Std::I64, Std::I64)), RegExp::Matcher)

matcher.find_from_in_bytes(from, bytes) is find_from over an array of bytes.

Parameters
  • from - The position the match has to begin at or after.
  • bytes - The bytes to search.
  • matcher - The regular expression and its scanner.

match_all

Type: Std::String -> RegExp::Matcher -> (Std::Array (Std::Array Std::String), RegExp::Matcher)

matcher.match_all(target) matches target against the regular expression, and reports the scanner as the match left it.

What it reports is what RegExp::match_all reports.

Parameters
  • target - The string to match against.
  • matcher - The regular expression and its scanner.

match_one

Type: Std::String -> RegExp::Matcher -> (Std::Option (Std::Array Std::String), RegExp::Matcher)

matcher.match_one(target) matches target against the regular expression, and reports the scanner as the match left it.

What it reports is what RegExp::match_one reports.

Parameters
  • target - The string to match against.
  • matcher - The regular expression and its scanner.

replace_all

Type: Std::String -> Std::String -> RegExp::Matcher -> (Std::String, RegExp::Matcher)

matcher.replace_all(target, replacement) replaces every stretch of target the regular expression matches with replacement, and reports the scanner as the work left it.

What it reports is what RegExp::replace_all reports.

Parameters
  • target - The string to work over.
  • replacement - The text to put in place of every match.
  • matcher - The regular expression and its scanner.

namespace RegExp::RegExp

compile

Type: Std::String -> Std::String -> Std::Result Std::ErrMsg RegExp::RegExp

RegExp::compile(pattern, flags) compiles pattern into a regular expression. flags change behavior of regular expression matching. The only flag is the global flag g, which match_one reads, so flags is "" or "g". Any other flag, or g given twice, is reported as an error.

find_all

Type: [?it : Std::Iterator, Std::Iterator::Item ?it = Std::Array (Std::I64, Std::I64)] Std::String -> RegExp::RegExp -> ?it

regexp.find_all(target) is an iterator over the matches in target, taken left to right, none of them overlapping another, each reported as where its groups stand. Each match is looked for when the iterator is advanced to it, so a program that stops early does not pay for the matches after.

A match is reported as one (begin, end) pair of byte positions per group, the whole match first. A group that captured nothing stands as (-1, -1). After a match that holds no byte the search goes on from the next byte. The global flag ("g") makes no difference here.

Example:

let regexp = RegExp::compile("([a-z]+)([0-9]+)", "").as_ok;
let found = regexp.find_all("abc012 def345").to_array;
assert_eq(|_|"", found, [[(0, 6), (0, 3), (3, 6)], [(7, 13), (7, 10), (10, 13)]])

Parameters
  • target - The string to search.
  • regexp - The regular expression.

find_all_in_bytes

Type: [?it : Std::Iterator, Std::Iterator::Item ?it = Std::Array (Std::I64, Std::I64)] Std::Array Std::U8 -> RegExp::RegExp -> ?it

regexp.find_all_in_bytes(bytes) is find_all over an array of bytes: an iterator over the matches in bytes, each reported as where its groups stand.

Parameters
  • bytes - The bytes to search.
  • regexp - The regular expression.

find_from

Type: Std::I64 -> Std::String -> RegExp::RegExp -> Std::Option (Std::Array (Std::I64, Std::I64))

regexp.find_from(from, target) finds the match in target that begins first at or after the byte position from, and reports where each of its groups stands, as find_all reports them. It reports none() where no match begins at or after from. A negative from counts as 0.

Example:

let regexp = RegExp::compile("[0-9]+", "").as_ok;
let found = regexp.find_from(4, "abc012 def345");
assert_eq(|_|"", found, some([(4, 6)]))

Parameters
  • from - The byte position the match has to begin at or after.
  • target - The string to search.
  • regexp - The regular expression.

find_from_in_bytes

Type: Std::I64 -> Std::Array Std::U8 -> RegExp::RegExp -> Std::Option (Std::Array (Std::I64, Std::I64))

regexp.find_from_in_bytes(from, bytes) is find_from over an array of bytes: the match in bytes that begins first at or after the position from.

Parameters
  • from - The position the match has to begin at or after.
  • bytes - The bytes to search.
  • regexp - The regular expression.

match_all

Type: Std::String -> RegExp::RegExp -> Std::Array (Std::Array Std::String)

regexp.match_all(target) matches target against regexp. All matching results will be returned including captured groups.

If the match against the regular expression fails, an empty array is returned.

This function is similar to String.matchAll() function of JavaScript.

match_one

Type: Std::String -> RegExp::RegExp -> Std::Option (Std::Array Std::String)

regexp.match_one(target) matches target against regexp. What it returns depends on whether regexp was compiled with the global flag g, as with String.prototype.match of JavaScript. This is the one function the flag changes.

Without g, it returns the groups of the first match. Group 0 is the substring the whole regular expression matches, and group 1 and beyond are the substrings each group captured, the empty string standing for a group that captured nothing.

let regexp = RegExp::compile("[a-z]+([0-9]+)", "").as_ok;
let groups = regexp.match_one("abc012 def345").as_some;
assert_eq(|_|"", groups, ["abc012", "012"])

With g, it returns the substring of every match, without the groups.

let regexp = RegExp::compile("[a-z]+([0-9]+)", "g").as_ok;
let groups = regexp.match_one("abc012 def345").as_some;
assert_eq(|_|"", groups, ["abc012", "def345"])

Where regexp matches nowhere in target, it returns none().

See String.match() of JavaScript.

matcher

Type: RegExp::RegExp -> RegExp::Matcher

regexp.matcher is the regular expression together with a scanner of its own.

A scanner works out what the automaton does with a byte the first time it reads that byte in that state, and keeps the answer. Matcher's matching functions hand the scanner back, so a program that matches many strings against one regular expression pays for the working out once, where RegExp's own matching functions make a scanner for each match and let it go.

Example:

let matcher = RegExp::compile("[a-z]+", "g").as_ok.matcher;
let (first, matcher) = matcher.match_all("abc def");
let (second, matcher) = matcher.match_all("ghi jkl");
assert_eq(|_|"", first, [["abc"], ["def"]]);;
assert_eq(|_|"", second, [["ghi"], ["jkl"]])

replace_all

Type: Std::String -> Std::String -> RegExp::RegExp -> Std::String

regexp.replace_all(target, replacement) replaces every match of regexp in target with replacement, reading replacement as JavaScript's String.prototype.replaceAll reads it: - $$ stands for a $, $& for the whole match, $` for the text before the match and $' for the text after it. - $n and $nn stand for the text group n or nn captured, and for the empty string where the group captured nothing. Two digits are read as one group number where the pattern has that group; otherwise the first digit is, and the second stands for itself. - $0, the number of a group the pattern lacks, and every other text stand for themselves.

Example:

let regexp = RegExp::compile("(\\w\\w)(\\w)", "").as_ok;
let result = regexp.replace_all("abc def ijk", "$2$1");
assert_eq(|_|"", result, "cab fde kij")

See String.replaceAll() of JavaScript.

Types and aliases

namespace RegExp

Matcher

Defined as: type Matcher = unbox struct { ...fields... }

A compiled regular expression together with the scanner it has built so far. See RegExp::matcher.

RegExp

Defined as: type RegExp = unbox struct { ...fields... }

Type of a compiled regular expression.

Traits and aliases

Trait implementations