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 method is available as of Version 6.9 of the Sirius Mods. 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). RegexReplaceCorresponding accepts two required and two optional arguments, and it returns a string. Specifying an invalid argument results in request cancellation.

Syntax

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

Syntax terms

outStr	A string set to the value of inStr with each matched substring replaced by the value of the replacementList item that corresponds to the matching %regList item.
%regList	A Stringlist object whose items are interpreted as regular expressions and applied to the inStr value.
inStr	The input string, to which the regular expressions in %regList are applied.
replacementList	A Stringlist, each of whose items is a potential replacement string for the substring of inStr that is matched by the corresponding item of %regList. 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 inStr that the item matches. .xxx$0 is an example of a valid replacement string, and .xxx concatenated with the portion of inStr that gets matched (by the corresponding %regList 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= string	The Options argument (name required) is an optional string of options. The options are single letters, which may be specified in uppercase or lowercase, in any combination, and separated by blanks or not separated. For more information about these options, see Regex processing. I Do case-insensitive matching between string and regex. S Dot-All mode: a dot (..) 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. For more information, see Regex processing. 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= num	The Status argument (name required) is optional; if specified, it is set to an integer code. These values are possible: &thinsp.n The number of replacements made. A value greater than 1 indicates option .G was in effect. &thinsp.0 No match: :hp1.inStr:ehp1. not matched by any :hp1.%regList:ehp1. items. -2 Syntax or other error: for example, the number of items in %regList does not equal the number in replacementList; or a %regList item exceeds 6124 bytes; or %regList 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 %regList 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 Version 7.0 of the Sirius Mods, an invalid regex results in a Status value of .-1. If you omit this argument and a negative Status value is to be returned, the run is cancelled.

Usage notes

• It is strongly recommended that you protect your environment from regex processing demands on PDL and STBL space by setting, say, .UTABLE LPDLST 3000 and .UTABLE LSTBL 9000. For further discussion of this, see User Language.
• Items in %regList must not exceed 6124 bytes. However, the inStr value and items in replacementList may exceed 6124 bytes.
• For information about additional methods and $functions that support regular expressions, see Regex processing.

Examples

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:<var>RegexReplaceCorresponding</var> (%inStr, %repList, Options=%opt, Status=%st)

Print 'Status from ReplaceCorresponding is ' %st
Print 'Output<var>String</var>: ' %outStr
...

The result would be:

Status from ReplaceCorresponding is 3
Output<var>String</var>: &&1&&2&&d