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.
The source for this interactive example is stored in a GitHub repository. If you'd like to contribute to the interactive examples project, please clone https://github.com/mdn/interactive-examples and send us a pull request.
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 (ECMA-262) The definition of 'RegExp.prototype[@@replace]' in that specification. |
Browser compatibility
Desktop | Mobile | Server | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
@@replace | Chrome Full support 50 | Edge Full support 79 | Firefox Full support 49 | IE No support No | Opera Full support 37 | Safari Full support 10 | WebView Android Full support 50 | Chrome Android Full support 50 | Firefox Android Full support 49 | Opera Android Full support 37 | Safari iOS Full support 10 | Samsung Internet Android Full support 5.0 | nodejs Full support 6.0.0 |
Legend
- Full support
- Full support
- No support
- No support