xcall REGEX2, spattern, status, subject, flags, rpattern, outstr
REGEX2 supports a replacement operation, similar to that of MX_TRANSCOPY, except that it acts on a single string subject, pattern and replacement specification rather than a file-based set of them.
Parameters
spattern (String) [in]
search pattern, equivalent to the pattern parameter in REGEXXS subroutine.
status, subject
same as for REGEX.
flags
Same as for REGEX except for the option flag PCREX_REPLACE_CASE, which only applies to REGEX2.
rpattern (String) [in]
replacement pattern, optionally including \# clauses referring to numbered capture sub-matches in the search pattern.
outstr (String) [out]
the string resulting from the replacement operation. If there were no matches (status < 1), then it will equal subject .
Consistent with the regular expression standard, parentheses in the search pattern mark sub-pattern capture groups which can then be referenced in the replacement pattern. These and any other special characters in the search pattern must be escaped by a leading backslash to treat them as literal. However, in the replacement pattern, the only special character is the backslash, used with a number to reference a captured sub-pattern (e.g. "\1").
As with MX_TRANSCOPYXS, the search and replace operation repeats until there are no more matches.
Example
To replace all occurrences of "[#]" with "(#)" (where # is an integer of any size), you could use the following:
spattern = \[(\d+?)\] ! series of digits within [brackets]
rpattern = (\1) ! the matched digits, now with (parens)
This combination would replace "Funkhouser[13], Tavares[172], Griffin[9x]" with "Funkhouser(13), Tavares(172), Griffin[9x]". (The third bracketed expression doesn't match the search pattern because of the "x".)
See Also
History
2025 December, A-Shell 7.0.1781: PCREX_REPLACE_CASE flag added.
2023 September, A-Shell 6.5.1743: Function added to A-Shell.
