Replace (Regex function)

Replace regex match(es) (Regex class)

This function replaces the parts of a string that match the regular expression in the Regex object and returns the string with the replacements.

Syntax

%string = regex:Replace( string, [replacement], [Options= string])

Syntax terms

A string of single letter options, which may be specified in uppercase or lowercase, in any combination, and blank separated or not. These options are a subset of Common regex options. The only acceptable options (case-independent) are A for "as-is", G for "global" (replace all occurrences), and T for trace.

%string	A copy of the input string after matches are replaced using the appropriate replacement string.
regex	The Regex object.
string	The string to test against the Regex object.
replacement	The string that replaces the substrings of string that regex matches. Except when the A option is specified (as described at Common regex options), you can include markers in the replacement value to indicate where to insert corresponding captured strings — strings matched by capturing groups (parenthesized subexpressions) in the reular expression, if any. 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 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

Usage notes

• If the regular expresion specified in the constructor call was Unicode, this method causes request cancellation. To test if a Regex object was created with a Unicode regular expression check the IsUnicode property.
• There is no way to undo the A, G, and T options if they were specified on the constructor so if a Regex objects sometimes needs these options and sometimes not, they should be specified on each Replace call.

See also

Regex class	List of Regex methods	Regex methods syntax
Notation conventions for methods