Replace
Replaces the matches of the pattern in a string and returns the result.
Syntax: object.Replace ( sourceString, replaceString ) As String
- object
- required An object expression that evaluates to a RegExp.
- sourceString
- required A String, the text to search. The argument is not changed.
- replaceString
- required A String, the text that replaces each match. It can hold the substitution items in the table below.
Returns a new String with the replacements made. It is sourceString unchanged when there is no match.
Substitution items
A $ in replaceString starts a substitution item. Any other text is copied as it is.
| Item | Is replaced with |
|---|---|
$$ | A single $. |
$& | The matched text. |
$` | The part of sourceString before the match. |
$' | The part of sourceString after the match. |
$n | The text of numbered group n, counting from 1. All the digits after the $ are read as the number. It is an empty string when the group matched nothing or the pattern has no such group. $0 raises a run-time error. |
$<name> | The text of the group written (?<name>...). It is an empty string when the group matched nothing or no group has the name. |
$~ | Nothing. The item is dropped. |
A $ at the end of replaceString, or followed by a character that is not in the table, raises error vbObjectError + 3031. The error is raised even when sourceString has no match, so a literal $ is written $$.
Note
VBScript’s RegExp copies into the result, as written, any $ that does not start one of its own items ($$, $&, $`, $' and $n). Here a $ at the end or before another character raises an error, $0 raises an error, $~ is dropped and $n of a group the pattern does not have is an empty string. A replacement string written for VBScript that holds a literal $ needs $$.
Remarks
With Global set to False, only the first match is replaced. With Global set to True, every match is. IgnoreCase, MultiLine and DotAll change what counts as a match.
An invalid pattern raises the compile error, with the number in LastErrorNumber and the description in LastError. Check IsValid first to avoid it.
Example
Dim re As RegExp
Set re = New RegExp
re.Pattern = "(\w+)@(\w+)\.com"
Debug.Print re.Replace("ann@example.com, bob@test.com", "$2:$1") ' example:ann, bob@test.com
re.Global = True
Debug.Print re.Replace("ann@example.com, bob@test.com", "$2:$1") ' example:ann, test:bob
re.Pattern = "\d+"
Debug.Print re.Replace("5 and 12", "$$$&") ' $5 and $12
re.Pattern = "(?<first>\w+) (?<last>\w+)"
Debug.Print re.Replace("Ada Lovelace", "$<last>, $<first>") ' Lovelace, Ada