# REGEX2

> [HTML Version](regex2_sbr.htm)

**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](string.htm.md))  \[in\] 

search pattern, equivalent to the _pattern_ parameter in [REGEX](regex_sbr.htm.md)[XS](keyword-types.htm.md) subroutine.

_status, subject_

same as for REGEX.

_flags_

Same as for REGEX except for the [option flag](optionsflags.htm.md) PCREX\_REPLACE\_CASE, which only applies to REGEX2.

_rpattern_  ([String](string.htm.md))  \[in\] 

replacement pattern, optionally including \\# clauses referring to numbered capture sub-matches in the search pattern. 

_outstr_  ([String](string.htm.md))  \[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\_TRANSCOPY](mx_transcopy.htm.md)[XS](keyword-types.htm.md), 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**

•	[REGEX](regex_sbr.htm.md)[XS](keyword-types.htm.md)

•	[MX\_TRANSCOPY](mx_transcopy.htm.md)[XS](keyword-types.htm.md)

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