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

See also

• String.prototype.replace()
• RegExp.prototype[@@match]()
• RegExp.prototype[@@search]()
• RegExp.prototype[@@split]()
• RegExp.prototype.exec()
• RegExp.prototype.test()