Regex

About

This class stores a regular expression pattern and can then perform regular expression operations based on that pattern.

API

constructor()

cs.js.Regex.new(pattern : Text)

Creates a new Regex object with the given regular expression pattern, which follows the same syntax as Match regex.

---

.match()

.match(str : Text { ; type : Text { ; start : Integer { ; throwOnBadPattern : Boolean }}}) : Collection

Matches str with This.pattern, starting at start (one-based) if given, or the first character if not given. If start < 1, it is normalized to 1.

If there is a match, a collection of matches is returned. If there is no match, null is returned.

If type is not passed or is "", this function returns after the first complete match in str. The returned collection contains:

• The complete match in element 0
• Any capture groups in the following elements
• An object with an .index property as the last element, which contains the one-based index at which the result was found

If type is "g", a collection is returned with all of the complete matches in str. No capture groups are returned.

If type is "a", a collection is returned with one item for each complete match in str. The type of each item depends on whether or not there are capture groups:

• If no capture groups are present, each item is the complete match.
• If one capture group is present, each item is the capture.
• If more than one capture group is present, each item is a collection whose items are the captures.

If This.pattern is malformed, null is returned. If throwOnBadPattern is true (the default is false), in addition a SyntaxError is thrown.

TIP

A more convenient way to use this function is to use _.regexMatch.

Examples

$text:="Sayeth Shakespeare: To be or not to be, that is the question"
$regex:=cs.js.Regex.new("(?i)(not )?(to be)")
$match:=$regex.match($text)
// => ["To be"; ""; "To be"; {"index": 21}]

$match:=$regex.match($text; "g")
// => ["To be"; "not to be"]

$match:=$regex.match($text; "a")
// => [["", "To be"], ["not ", "to be"]]

---

.replace()

.replace(str : Text; replacement : Text { ; count : Integer { ; throwOnBadPattern : Boolean }}) : Text
.replace(str : Text; replacement : Callable { ; count : Integer { ; throwOnBadPattern : Boolean }}) : Text

Replaces count matches of This.pattern in str. If count is not passed or is negative, all matches are replaced.

If replacement is a string, it can include the following special replacement patterns:

Pattern	Description
$$	Inserts "$"
$&	Inserts the matched substring
$`	Inserts the portion of the string that precedes the matched substring
$'	Inserts the portion of the string that follows the matched substring
$n	Inserts the nth capture, where n is a one-based positive integer less than 100

If replacement is a Callable, it is called with the following parameters:

Parameter	Type	Description
$1	Text	The matched substring (corresponds to $& above)
$2	Collection	The captures for the current match
$3	Integer	The one-based offset of the matched substring within the whole string being examined
$4	Text	The whole string being examined

If replacement is any other type, a TypeError is thrown and "" is returned.

The result of the formula is used as the replacement string.

If This.pattern is malformed, str is returned. If throwOnBadPattern is true (the default is false), in addition a SyntaxError is thrown.

TIP

A more convenient way to use this function is to use _.regexReplace.

Examples

// replace all occurrences of the pattern if $count is not passed
$regex:=cs.js.Regex.new("\\bbar\\b")
$result:=$regex.replace("foo is bar, bar is foo"; "foo")
// => "foo is foo, foo is foo"

// replace the first $count occurrences of the pattern if $count is passed
$regex:=cs.js.Regex.new("\\bbar\\b")
$result:=$regex.replace("foo is bar, bar is foo"; "foo"; 1)
// => "foo is foo, bar is foo"

// replace \"$$\" in a replacement string with \"$\""
$regex:=cs.js.Regex.new("\\bfoo\\b")
$result:=$regex.replace("foo = 7"; "$$foo")
// => "$foo = 7"

// replace \"$&\" in a replacement string with the matched substring
$regex:=cs.js.Regex.new("\\bfoo\\b")
$result:=$regex.replace("foo = 7"; "$$$&bar")
// => "$foobar = 7"

// replace \"$`\" in a replacement string
// with what precedes the matched substring
$regex:=cs.js.Regex.new("foo")
$result:=$regex.replace("barfoobaz"; "($`)")
// => "bar(bar)baz"

// replace \"$'\" in a replacement string
// with what follows the matched substring
$regex:=cs.js.Regex.new("foo")
$result:=$regex.replace("barfoobaz"; "($')")
// => "bar(baz)baz"

// replace \"$n\" in a replacement string with the indexed capture
$regex:=cs.js.Regex.new("var (\\w+): (\\w+)")
$result:=$regex.replace("var foo: Integer"; "var $$$1: $2")
// => "var $foo: Integer"

// Callable replacement
$replacer:=Formula(_.format("match: '${1}', captures: ${2}, offset: ${3}, source: '${4}'"; $1; $2; $3; Substring($4; $3; 8)))
$pattern:="^var (\\w+): (\\w+)$"
$source:="var foo: Integer"
$result:=cs.js.Regex.new($pattern).replace($source; $replacer)
// => "match: 'var foo: Integer', captures: [\"foo\",\"Integer\"], offset: 1, source: 'var foo:'"

---

.split()

.split(str : Text { ; limit : Integer { ; throwOnBadPattern : Boolean }}) : Collection

Splits str using This.pattern as the separator. Returns a collection of strings split at each point where the separator occurs in the given string.

If the separator does not occur in str, the returned collection contains one element consisting of str. If the separator is an empty string, str is converted to a collection having one element for each character of str.

When limit is provided, this function splits the string at each occurrence of the specified separator but stops when limit entries have been placed into the results. It may still contain fewer entries than limit if the end of the string is reached before the specified limit is reached. The left over text when limit is reached is not returned in the results. A negative limit is considered no limit.

If This.pattern is malformed, the returned collection contains one element consisting of str. If throwOnBadPattern is true (the default is false), in addition a SyntaxError is thrown.

TIP

A more convenient way to use this function is to use _.regexSplit.

Example

$regex:=cs.js.Regex.new("\\s+")
$result:=$regex.split("foo  bar\nbaz")
// => ["foo"; "bar"; "baz"]

$result:=$regex.split("foo  bar\nbaz"; 2)
// => ["foo"; "bar"]

$result:=$regex.split("foobar")
// => ["foobar"]