The purpose of this function is to find text in one or more fields, a named variable or each item of a list in a named variable and to replace it with other, possibly empty, text. If a delimiter is specified when replacing in a list and it evaluates to an empty string at runtime, a default (\~) will be assumed.
When in stepwise execution mode and you're replacing text in a named variable, the function is only performed once.
All text fields may contain any of the escape sequences described in Escape Sequences.
There are three modes of replacing:
You control what and how much text gets replaced by choosing one of:
- Match String
- In this mode you are looking for occurrences of the from pattern string.
- Match Words
- In this mode you match whole words only. For the purposes of this function a match whole word test fails if:
the first character in the from pattern is alphanumeric and the character preceding the match is alphanumeric.
or if:
the last character in the from pattern is alphanumeric and the character following the match is alphanumeric.- Match Characters
- In this case you are looking for individual characters in the from pattern. If found they are replaced with the replace pattern. eg: If the Title field contains a1b2c3
Replace "0123456789", match characters in the Title field with "#"
will change the Title to a#b#c#
- All
- Replace all occurrences of the matched pattern.
- First
- Replace only the first occurrence of the matched pattern.
- At Start
- Replace only one occurrence of the matched pattern and only if it is at the very start of a field.
- At End
- Replace only one occurrence of the matched pattern and only if it is at the very end of a field.
- Last
- Replace only the last occurrence of the matched pattern. Note this option is not supported when matching words.
- Leading
- Replace all occurrences of the matched pattern at the very start of a field with one occurrence of the replacement text. Note this option is not supported when matching words.
- Trailing
- Replace all occurrences of the matched pattern at the very end of a field with one occurrence of the replacement text. Note this option is not supported when matching words.
- Compress
- This option is only valid when matching characters. Any sequence of characters in the from pattern is replaced with a single occurrence of the replacement text.
You can select Ignore case and make the function case insensitive when matching the Replace text. When matching characters the function is always case sensitive.
You can specify that you want to match and replace one of a number of supplied strings by specifying the Or matching option and separating the strings with | characters. Note that the Oring component separation occurs before any escape sequences are applied. Replacements will be successively attempted with each string in the supplied list. If one of the strings is matched, the Or matching will terminate immediately after the replacements are applied.
If you want to be able to test if any replacements occurred, select the Set state option. When selected, if any replacements occurred the action test state will be set to true, otherwise it will be set to false.
Let's say you want the first occurrence of 'featuring', 'feat.' or 'feat' in any alphabetic case in the Title field to be replaced with 'featuring'. Select the Title field, Ignore case, Once, Match words and Or matching. Set the replace field to featuring|feat.|feat and the with field to featuring.
Information on alternate means of parsing or scanning