set changed = aString.replace(regExpPattern, replacement)
set changed = replace(LITERAL, regExpPattern, replacement)
Semantics
All strings that correspond to the regular expression pattern will be replaced with the string replacement. If the pattern does not match, the unchanged string will be returned. Returns a new string. The state of the current string is not changed.
Substitutables
aString
Can be any variable or object attribute having type String.
replacement
Can be any variable or object attribute having type String.
In case of capturing groups with the regular expression, replacement may also contain special syntax. This is why replacement will also be interpreted by the Runtime and must not contain unescaped $ and \ signs (see also Replacement Text). If you are not sure of the contents of your replacement, you can use the replace function itself on the replacement, like
set changed = aString.replace(regExpPattern, replacement.replace('\$', '\\\\\$'));
Cannot execute replace operations on empty strings.
FUSSM/12
Cannot construct replace matcher finding occurrences of <string> in <string>.
FUSSM/13
Cannot execute replace operations using an empty replace string.
FUSSM/14
Cannot compile the regular expression <string> in replace(). Error on line <number>, column <number>.
FUSSM/15
Cannot construct replace matcher finding occurrences of <string> in <string>.
FUSSM/16
Cannot replace all occurences of <string> in string <string> by <string>.
Examples
set changed = stringSet.s1.replace("X.+", "A");
Trimming spaces and whitespaces
If you want to trim leading or trailing spaces or whitespaces of a string, you can use regular expressions in order to remove them.
Task
Action Script
Trimming leading spaces
set trimmedString = stringSet.s1.replace("^[ ]+", "");
Trimming trailing spaces
set trimmedString = stringSet.s1.replace("[ ]+$", "");
Trimming leading and trailing spaces
set trimmedString = stringSet.s1.replace("^[ ]+|[ ]+$", "");
Trimming leading spaces and whitespaces (\t)
set trimmedString = stringSet.s1.replace("^[ \t]+", "");
Replacing Parts of a Regular Expression
If you want to replace parts of a string that contains a regular expression, you may run into the problem that the Runtime will interpret the matching part. In this case, adorn the matching part expression with \Q and \E to mark it as a literal string, so the Runtime will simply take it as it is for comparison (see also Meta Characters).
set pdfFilenamePattern = "invoice_\d{8}\d{6}\d{5}((\.pdf)|(\.PDF))";
set matchingPart = "\d{8}\d{6}\d{5}";
set replacement = "12345678_123456_12345";
set changed = replace(pdfFilenamePattern, concat('\Q', matchingPart, '\E'), replacement);
The same applies if the replacement contains a regular expression.