RegExp.prototype[@@replace]()

[@@replace]() メソッドは、 replacement によって文字列内の this パターンの一部または、すべての一致を置き換えて、置換結果を新しい文字列として返します。replacement は文字列か関数をすべてのマッチごとに呼び出されるようにできます。

構文

regexp[Symbol.replace](str, newSubStr|function)

パラメーター

str

置換対象の String。

newSubStr (replacement)

部分を置換する String。特殊な置換パターンの数値がサポートされている：String.prototype.replace() ページの Specifying a string as a parameter セクションを見てください。

function (replacement)

新しい部分文字列を生成するために呼び出される関数。この関数に提供される引数については、String.prototype.replace() ページの Specifying a function as a parameter セクションを見てください。

戻り値

置換によって置き換えられたパターンの一部またはすべてのマッチを持つ新しい文字列。

説明

pattern 引数が RegExp オブジェクトだった場合、このメソッドは String.prototype.replace() で内部的に呼び出されます。たとえば、次の 2 つの例は同じ結果を返します。

'abc'.replace(/a/, 'A');

/a/[Symbol.replace]('abc', 'A');

このメソッドは、RegExp サブクラスの置換動作をカスタマイズするために存在しています。

pattern 引数が RegExp オブジェクトではない場合、String.prototype.replace() はこのメソッドの呼び出しや RegExp オブジェクトの生成を行いません。

例

直接呼出し

this と引数の順序が異なる点を除いて、このメソッドは String.prototype.replace() とほどんど同じ使い方ができます。

var re = /-/g; 
var str = '2016-01-01';
var newstr = re[Symbol.replace](str, '.');
console.log(newstr);  // 2016.01.01

サブクラスで @@replace を使用する

既定の動作を修正するために、RegExp のサブクラスで [@@replace]() メソッドをオーバーライドできます。

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

仕様

ブラウザ実装状況

関連項目

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