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
<var>regexp</var>[Symbol.replace](str, <var>newSubStr</var>|<var>function</var>)
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 | Status | Comment |
---|---|---|
ECMAScript 2015 (6th Edition, ECMA-262) The definition of 'RegExp.prototype[@@replace]' in that specification. |
Standard | Initial definition. |
ECMAScript 2017 Draft (ECMA-262) The definition of 'RegExp.prototype[@@replace]' in that specification. |
Draft |
Browser compatibility
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|
Basic support | ? | 49 (49) | ? | ? | ? |
Feature | Android | Chrome for Android | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|
Basic support | ? | ? | 49.0 (49) | ? | ? | ? |
See also
String.prototype.replace()
RegExp.prototype[@@match]()
RegExp.prototype[@@search]()
RegExp.prototype[@@split]()
RegExp.prototype.exec()
RegExp.prototype.test()
License
© 2016 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-us/docs/web/javascript/reference/global_objects/regexp/@@replace