RegexReplaceCorresponding (Stringlist function)
Replace substrings that match regex with items in a Stringlist (Stringlist class)
This method searches a given string for matches to one of multiple regular expressions contained in a list, and it replaces found matches with or according to a string contained in a list that corresponds to the regex list.
The regex list items are treated as mutually exclusive alternatives, and the function stops as soon as an item matches and the replacement is made. A "global" option is also available to continue searching and replacing within the given string using the matching regex item until no more matches are found.
RegexReplaceCorresponding uses the rules of regular expression matching (information about which is provided in "Regex processing rules").
RegexReplaceCorresponding accepts two required and two optional arguments, and it returns a string.
%outString = sl:RegexReplaceCorresponding( inString, replacementList, - [Options= string], - [Status= %output]) Throws InvalidRegex
|outString||A string set to the value of inString with each matched substring replaced by the value of the replacementList item that corresponds to the matching sl item.|
|sl||A Stringlist object whose items are interpreted as regular expressions and applied to the inString value.|
|inString||The input string, to which the regular expressions in sl are applied.|
A Stringlist, each of whose items is a potential replacement string for the substring of inString that is matched by the corresponding item of sl.
Except when the
Any character after the dollar sign other than a zero is an error. Multiple zeroes (as many as 9) are permitted; a digit following such a string of zeroes must be escaped.
You can also use the format
The only characters you can escape in a replacement string are dollar sign (
For example, since the scan for the number that accompanies the meta-$ stops at the first nonnumeric, you use
|Options||This is an optional, name required, parameter supplying 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".
|Status||The Status argument (name required) is optional; if specified, it is set to an integer code. These values are possible:
- All errors in RegexReplaceCorresponding, including invalid argument(s) result in request cancellation.
- It is strongly recommended that you protect your environment from regular expression processing demands on PDL and STBL space by setting, say,
UTABLE LPDLST 3000and
UTABLE LSTBL 9000. See SOUL programming considerations.
- Items in sl must not exceed 6124 bytes. However, the inString value and items in replacementList may exceed 6124 bytes.
- For information about additional methods and $functions that support regular expressions, see Regex_processing.
In the following code fragment, the second item in regex list
%regList is the first to match the input string
inStr. The subexpression in that item performs no special capturing function — the parentheses are for grouping only. Since
%opt='g' is specified, three replacements are made (using the corresponding, second, item in
... %regList = new text to %regList abcx a(bc?) abcd end text %repList = new text to %repList & && &&& end text %inStr = 'abc1abc2abcd' %opt='g' %outStr = %regList:RegexReplaceCorresponding(%inStr, %repList, Options=%opt, Status=%st) Print 'Status from ReplaceCorresponding is ' %st Print 'Output String: ' %outStr ...
The result would be:
Status from ReplaceCorresponding is 3 Output String: &&1&&2&&d