Module regex
ballerina/regex Ballerina library
Deprecation Notice: This library is deprecated and will no longer be maintained or updated. Instead, it is recommended to use the ballerina/lang.regexp library for continued support and updates. For more information, see the new RegExp type example, RegExp operations example, and Regular expressions feature guide.
Overview
This module provides APIs for searching, splitting, and replacing the set of characters of a string. These APIs are using a
regular expression as a String to perform these operations by finding the string matches.
Regular expressions, are notations for describing sets of character strings. If a particular string is in the set described by a regular expression, the regular expression matches that string.
For information on the operations, which you can perform with the regex module, see the below Functions.
Functions
matches
Checks whether the given string matches the provided regex.
Note that \\ is used as for escape sequence and \\\\ is used to insert a backslash
character in the string or regular expression. The following special characters should be escaped
in the regex definition.
Special Characters: ., +, *, ?, ^, $, (, ), [, ], {, }
boolean isMatched = regex:matches("Ballerina is great", "Ba[a-z ]+");
Parameters
- stringToMatch string - The string to match the regex
- regex string - The regex to match the string
Return Type
- boolean -
trueif the provided string matches the regex or elsefalse
replace
function replace(string originalString, string regex, Replacement replacement, int startIndex) returns stringReplaces the first substring that matches the given regex with
the provided replacement string or string returned by the provided function.
Note that \\ is used as for escape sequence and \\\\ is used to insert a backslash
character in the string or regular expression. The following special characters should be escaped
in the regex definition.
Special Characters: ., +, *, ?, ^, $, (, ), [, ], {, }
string result = regex:replace("Ballerina is great", "\\s+", "_");
Parameters
- originalString string - The original string to replace the first occurrence of the substring that matches the provided regex
- regex string - The regex to match the first substring in the
originalStringto be replaced
- replacement Replacement - The replacement string or a function to be invoked to create the new substring to be used to replace the first match to the given regex
- startIndex int (default 0) - The starting index for the search
Return Type
- string - The resultant string with the replaced substring
replaceAll
function replaceAll(string originalString, string regex, Replacement replacement) returns stringReplaces each occurrence of the substrings, which match the provided
regex from the given original string value with the provided replacement string.
Note that \\ is used as for escape sequence and \\\\ is used to insert a backslash
character in the string or regular expression. The following special characters should be escaped
in the regex definition.
Special Characters: ., +, *, ?, ^, $, (, ), [, ], {, }
string result = regex:replaceAll("Ballerina is great", "\\s+", "_");
Parameters
- originalString string - The original string to replace the occurrences of the substrings that match the provided regex
- regex string - The regex to match the substrings in the
originalString, which is to be replaced
- replacement Replacement - The replacement string or a function to be invoked to create the new substring to be used to replace the first match to the given regex
Return Type
- string - The resultant string with the replaced substrings
replaceFirst
Replaces the first substring that matches the given regex with
the provided replacement string.
Note that \\ is used as for escape sequence and \\\\ is used to insert a backslash
character in the string or regular expression. The following special characters should be escaped
in the regex definition.
Special Characters: ., +, *, ?, ^, $, (, ), [, ], {, }
string result = regex:replaceFirst("Ballerina is great", "\\s+", "_");
Parameters
- originalString string - The original string to replace the first occurrence of the substring that matches the provided regex
- regex string - The regex to match the first substring in the
originalStringto be replaced
- replacement string - The replacement string to replace the first substring, which matches the regex
Return Type
- string - The resultant string with the replaced substring
Deprecated
This function will be removed in a later. Usereplaceinstead.
search
Returns the first substring in str that matches the regex.
Note that \\ is used as for escape sequence and \\\\ is used to insert a backslash
character in the string or regular expression. The following special characters should be escaped
in the regex definition.
Special Characters: ., +, *, ?, ^, $, (, ), [, ], {, }
regex:Match? result = regex:search("Betty Botter bought some butter but she said the butter’s bitter.", "\\b[bB].tt[a-z]*");
Parameters
- str string - The string to be matched
- regex string - The regex value
- startIndex int (default 0) - The starting index for the search
Return Type
- Match? - a
Matchrecord which holds the matched substring, or nil if there is no match
searchAll
Returns all substrings in string that match the regex.
Note that \\ is used as for escape sequence and \\\\ is used to insert a backslash
character in the string or regular expression. The following special characters should be escaped
in the regex definition.
Special Characters: ., +, *, ?, ^, $, (, ), [, ], {, }
regex:Match[] result = regex:searchAll("Betty Botter bought some butter but she said the butter’s bitter.", "\\b[bB].tt[a-z]*");
Return Type
- Match[] - An array of
Matchrecords
split
Returns an array of strings by splitting a string using the provided
regex as the delimiter.
Note that \\ is used as for escape sequence and \\\\ is used to insert a backslash
character in the string or regular expression. The following special characters should be escaped
in the regex definition.
Special Characters: ., +, *, ?, ^, $, (, ), [, ], {, }
string[] result = regex:split("Ballerina is great", " ");
Parameters
- receiver string - The string to split
- delimiter string - The delimiter is a regex, which splits the given string
Return Type
- string[] - An array of strings containing the individual strings that are split
Records
regex: Match
Holds the results of a match against a regular expression. It contains the match boundaries, groups, and group boundaries.
Fields
- Fields Included from *PartMatch
- groups Groups - Information about matched regex groups
regex: PartMatch
Holds the matched substring and its position in the input string.
Fields
- matched string - Matched substring
- startIndex int - The start index of the match
- endIndex int - The last index of the match
Object types
regex: Groups
Abstract object representation to hold information about matched regex groups.
get
Parameters
- index int -
Union types
regex: Replacement
Replacement
A type to be used to get a replacement string.