UnicodeRegexReplace (Unicode function)

Replace regex match(es) (Unicode class)

The UnicodeRegexReplace intrinsic function searches a given Unicode string for matches of a regular expression, and it replaces matches with, or according to, a specified replacement string. The function stops after the first match and replace, or it can continue searching and replacing until no more matches are found.

Matches are obtained according to the rules of regular expression matching.

Syntax

%outUnicode = unicode:UnicodeRegexReplace( regex, replacement, - [Options= string]) Throws InvalidRegex

Syntax terms

%outUnicode	Unicode
unicode	The input Unicode string, to which the regular expression regex is applied.
regex	A Unicode string that is interpreted as a regular expression and that is applied to the method object, unicode, to find the one or more substrings matched by regex.
replacement	The Unicode string that replaces the substrings of unicode that regex matches. Except when the A option is specified (as described below for the Options argument), you can include markers in the replacement value to indicate where to insert corresponding captured strings — strings matched by capturing groups (parenthesized subexpressions) in regex, if any. As in Perl, these markers are in the form $n, where n is the number of the capture group, and 1 is the number of the first capture group. n must not be 0 or contain more than 9 digits. If a capturing group makes no matches (is positional, for example), or if there was no nth capture group corresponding to the $n marker in a replacement string, the (literal) value of $n is used in the replacement string instead of the empty string. xxx$1 is an example of a valid replacement string, and $0yyy is an example of an invalid one. Or you can use the format $mn, where m is one of the following modifiers: U or u Specifies that the specified captured string should be uppercased when inserted. L or l Indicates that the captured string should be lowercased when inserted. The only characters you can escape in a replacement string are dollar sign ($), backslash (\), and the digits 0 through 9. So only these escapes are respected: \\, \$, and \0 through \9. No other escapes are allowed in a replacement string — this includes "shorthand" escapes like \d — and an "unaccompanied" backslash (\) is an error. For example, since the scan for the number that accompanies the meta-$ stops at the first non-numeric, you use 1$1\2 to indicate that the first captured string should go between the numbers 1 and 2 in the replacement string. An invalid replacement string results in request cancellation.
Options	This optional, name required, parameter is a String of single-letter options, which may be specified in uppercase or lowercase, in any combination, and blank separated or not, as you prefer. For more information about these options, see Common regex options: I Do case-insensitive matching between unicode and regex. S Dot-All mode: a period (.) can match any character, including carriage return and linefeed. M Multi-line mode: let anchor characters match end-of-line indicators wherever the indicator appears in the input string. M mode is ignored if C (XML Schema) mode is specified. C Do the match according to XML Schema regex rules. Each regex is implicitly anchored at the beginning and end, and no characters serve as anchors. G Replace every occurrence of the match, not just (as in non-G mode) the first matched substring only. A Copy the replacement string as is. Do not recognize escapes; interpret a $n combination as a literal and not as a special marker; and so on.

Usage notes

• It is strongly recommended that you protect your environment from regular expression processing demands on PDL and STBL space by setting, say, UTABLE LPDLST 3000 and UTABLE LSTBL 9000. See SOUL programming considerations.
• Within a regular expression, characters enclosed by a pair of unescaped parentheses form a "subexpression." A subexpression is a capturing group if the opening parenthesis is not followed by a question mark (?). A capturing group that is nested within a non-capturing subexpression is still a capturing group.
• In Perl, $n markers ($1, for example) enclosed in single quotes are treated as literals instead of as "that which was captured by the first capturing parentheses." RegexReplace uses the A option of the Options argument for this purpose.
• Matching of regex may "succeed" but yet match no characters. For example, a quantifier like ? is allowed by definition to match no characters, though it tries to match one. UnicodeRegexReplace honors such a zero-length match by substituting the specified replacement string at the current position. If the global option is in effect, the regex is then applied again one position to the right in the input string, and again, until the end of the string. The regex 9? globally applied to the string abc with a comma-comma (,,) replacement string results in this output string: ,,a,,b,,c,,.
• For information about additional methods that support regular expressions, see Regex processing.

Examples

This request replaces a word with a different spelling, then adds an entirely lowercased copy of an initial phrase:

begin %regexU is unicode %strU is unicode %oU is unicode %strU = 'At the centre of it all, your eyes' %regexU = 'centre'; %oU = %str:unicodeRegexReplace(%regexU, 'center') printText 'center': {%strU:unicodeRegexReplace(%regexU, 'center') %regexU = '(.*[,])' printText $1 $L1  : {%oU:unicodeRegexReplace(%regexU, '$1 $L1')} end

The result of the above fragment is:

'center': At the center of it all, your eyes $1 $L1  : At the center of it all, at the center of it all, your eyes

Note: To add a third occurrence of the phrase "at the center of it all" to the result above, change the regex to (.*?[,]), which non-greedily captures only the first occurrence. Using the (.*[,]) regex against an initial string that has two occurrences of the phrase and two commas, the method would capture to and including the second comma, and would output four occurrences.

See also

Float class String class Unicode class	List of Float methods List of String methods List of Unicode methods List of Intrinsic methods	Float methods syntax String methods syntax Unicode methods syntax
Notation conventions for methods