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

JavaScript
<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 in String.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.

JavaScript
'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.

JavaScript
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.

JavaScript
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

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

JavaScript Method Prototype Reference RegExp Regular Expressions