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.

Syntax

%outString = sl:RegexReplaceCorresponding( inString, replacementList, - [Options= string], - [Status= %output]) Throws InvalidRegex

Syntax terms

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.
replacementList	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 A option is specified (as described below for the Options argument), you can include $0 markers in replacementList items as placeholders for the substring of inString that the item matches. xxx$0 is an example of a valid replacement string, and xxx concatenated with the portion of inString that gets matched (by the corresponding sl item) constitute the replacement string. 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 $m0, where m is one of the following modifiers: U or u Specifies that the matched substring should be uppercased when inserted. L or l Indicates that the matched substring 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 nonnumeric, you use 1$0\0 to indicate that the first matched substring should go between the numbers 1 and 0 in the replacement string.
Options	This is an optional, but nameRequired, 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". I Do case-insensitive matching between string and regex. S Dot-All mode: a period (.) can match any character, including carriage return and linefeed. M Multi-line mode: let anchor characters match end-of-line indicators wherever the indicator appears in the input string. M mode is ignored if C (XML Schema) mode is specified. C Do the match according to "XML Schema regex rules". Each regex is implicitly anchored at the beginning and end, and no characters serve as anchors. G Replace every occurrence of the match, not just (as in non-G mode) the first matched substring only. A Copy the replacement string as is. Do not recognize escapes; interpret a $n combination as a literal and not as a special marker; and so on.
Status	The Status argument (name required) is optional; if specified, it is set to an integer code. These values are possible: n The number of replacements made. A value greater than 1 indicates option G was in effect. 0 No match: inString not matched by any sl items. -2 Syntax or other error: for example, the number of items in sl does not equal the number in replacementList; or a sl item exceeds 6124 bytes; or sl is empty. -5 An invalid string in a replacementList item. For example, an invalid escape sequence, or a $ followed by any characters other than one or more (but no more than 9) zeroes. -1nnn A regex in sl is invalid. nnn (the absolute value of the return minus 1000) gives the 1-based position of the character being scanned when the error was discovered. The value for an error occurring at end-of-string is the length of the string + 1. Prior to Sirius Mods Version 7.0, an invalid regex results in a Status value of -1. Note: If you omit this argument and a negative Status value is to be returned, the run is cancelled.

Usage notes

• 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 3000 and UTABLE LSTBL 9000. See "User Language 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".
• RegexReplaceCorresponding is available as of "Sirius Mods" Version 6.9.

Examples

1. 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 %repList):

   ... %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

See also

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