The purpose of this statement is to find text in one or more fields, a named variable or each field specified in a list in a named variable and to replace it with other, possibly empty, text. Which fields or text strings you are processing is discussed in Statement Source/Target Determination. The same topic describes the ability to treat each field or named variable as a list where each list component will be processed.
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#- Regular Expression
- Replace using a regular expression. While the Regular Expression statement has far more options it cannot process more than one field at a time. See the documentation for the Regular Expression statement for more information on how the replace and with fields are processed.
- 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 elect to make the match process case insensitive and/or diacritical mark insensitive. 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 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, Case insensitive, Once, Match words and Or matching. Set the replace field to featuring|feat.|feat and the with field to featuring.
Field Selection Modes in Tables
Information on alternate means of parsing or scanning