###Function###
StringRegExpReplace

###Description###
Replace text in a string based on regular expressions.

###Syntax###
StringRegExpReplace ( "test", "pattern", "replace" [, count = 0] )


###Parameters###
@@ParamTable@@
test
	The string to check
pattern
	The regular expression to compare.  See <A href="StringRegExp.htm">StringRegExp</a> for pattern definition characters.
replace
	The text to replace the regular expression matching text with.  To insert matched group text, \0 - \9 (or $0 - $9) can be used<strong> as</strong> back-references. (See remarks)
count
	[optional] The number of times to execute the replacement in the string.  The default is 0.  Use 0 for global replacement.
@@End@@

###ReturnValue###
@@ReturnTable@@
Success:	an updated string based on regular expressions. Check @extended for the number of replacements performed.
Failure:	sets the @error flag to non-zero.
@error:	2 = Pattern invalid.  @extended = offset of error in pattern.
@@End@@


###Remarks###
To separate back-reference replacements from actual (replaced) numbers, wrap them with curly braces, i.e: "${1}5".
If a "\" needs to be in the replaced string it must be doubled. This is a consequence of the back-references mechanism.
The "\" and "$" replacement formats are the only valid back-references formats supported.

See also the <a href="../tutorials/regexp/regexp.htm">Regular Expression</a> tutorial, in which you can run a script to test your regular expression(s).


###Related###
StringRegExp, StringReplace


###Example###
@@IncludeExample@@
