Mozilla's getting a new look. What do you think? https://mzl.la/brandsurvey

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

'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

Document Tags and Contributors

 Contributors to this page: h4writer, fscholz, arai
 Last updated by: h4writer,