RegExp.prototype[@@replace]()
The [@@replace]()
method replaces some or all matches of
a this
pattern in a string by a replacement
, and returns the
result of the replacement as a new string. The replacement
can be a string
or a function to be called for each match.
Syntax
regexp[Symbol.replace](str, newSubStr|function)
Parameters
str
-
A
String
that is a target of the replacement. newSubStr
(replacement)-
The
String
that replaces the substring. A number of special replacement patterns are supported; see the Specifying a string as a parameter section inString.prototype.replace()
page. function
(replacement)-
A function to be invoked to create the new substring. The arguments supplied to this function are described in the Specifying a function as a parameter section in
String.prototype.replace()
page.
Return value
A new string with some or all matches of a pattern replaced by a replacement.
Description
This method is called internally in String.prototype.replace()
if the
pattern
argument is a RegExp
object. For example, following
two examples return same result.
'abc'.replace(/a/, 'A');
/a/[Symbol.replace]('abc', 'A');
This method exists for customizing replace behavior in RegExp
subclass.
If pattern argument is not a RegExp
object,
String.prototype.replace()
doesn't call this method, nor creates a
RegExp
object.
Examples
Direct call
This method can be used in almost the same way as
String.prototype.replace()
, except the different this
and the
different arguments order.
var re = /-/g;
var str = '2016-01-01';
var newstr = re[Symbol.replace](str, '.');
console.log(newstr); // 2016.01.01
Using @@replace in subclasses
Subclasses of RegExp
can override the [@@replace]()
method
to modify the default behavior.
class MyRegExp extends RegExp {
constructor(pattern, flags, count) {
super(pattern, flags);
this.count = count;
}
[Symbol.replace](str, replacement) {
// Perform @@replace |count| times.
var result = str;
for (var i = 0; i < this.count; i++) {
result = RegExp.prototype[Symbol.replace].call(this, result, replacement);
}
return result;
}
}
var re = new MyRegExp('\\d', '', 3);
var str = '01234567';
var newstr = str.replace(re, '#'); // String.prototype.replace calls re[@@replace].
console.log(newstr); // ###34567
Specifications
Specification |
---|
ECMAScript Language Specification # sec-regexp.prototype-@@replace |
Browser compatibility
BCD tables only load in the browser