The RegSub( pattern, text, template ) function performs regular expression search and replace on text. RegSub tests whether the string text matches the regular expression pattern. If a match occurs, the string template is copied as the output, but substrings can be replaced with the portion of text that matched pattern as follows.

The substring & is replaced with the portion of text that matched the entire regular expression pattern. If d is a single digit, then the substring \d is replaced with the substring of text matching the d-th parenthesized subexpression of pattern.

If text does not match pattern, the value FAIL is returned.

Note: RegSub is a very low-level procedure. For most applications, StringTools[RegSubs] is easier to use.

This function is part of the StringTools package, and so it can be used in the form RegSub(..) only after executing the command with(StringTools). However, it can always be accessed through the long form of the command by using the form StringTools[RegSub](..).

All of the StringTools package commands treat strings as (null-terminated) sequences of $8$-bit (ASCII) characters.  Thus, there is no support for multibyte character encodings, such as unicode encodings.

$\mathrm{with}\left(\mathrm{StringTools}\right)\:$

$\mathrm{RegSub}\left(''((a))''\,''abc''\,''gu\backslash \backslash 1v\backslash \backslash 2''\right)$

$''guava''$

$''abbbcd-abbbc''$

$''abcd-bc-d''$

$''effgz-effgz-''$

$''effgz-effgz-''$

$\mathrm{RegSub}\left(''(.*)c(anad[ai])(.*)''\,''Maple\; is\; canadian''\,''\backslash \backslash 1C\backslash \backslash 2\backslash \backslash 3''\right)$

$''Maple\; is\; Canadian''$