RegExp.prototype[@@replace]()

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

構文

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

引数

str
置換対象の String
newSubStr (replacement)
部分を置換する String。特殊な置換パターンの数値がサポートされている:String.prototype.replace() ページの引数としての文字列の指定セクションを見てください。
function (replacement)
新しい部分文字列を生成するために呼び出される関数。この関数に提供される引数については、String.prototype.replace() ページの引数としての関数の指定セクションを見てください。

戻り値

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

説明

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

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

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

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

String.prototype.replace()pattern 引数が RegExp オブジェクトではない場合、このメソッドの呼び出しや 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

仕様

仕様 状態 コメント
ECMAScript 2015 (6th Edition, ECMA-262)
RegExp.prototype[@@replace] の定義
標準 初期定義。
ECMAScript (ECMA-262)
RegExp.prototype[@@replace] の定義
現行の標準

ブラウザー実装状況

Update compatibility data on GitHub
デスクトップモバイルサーバー
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewAndroid 版 ChromeAndroid 版 FirefoxAndroid 版 OperaiOSのSafariSamsung InternetNode.js
@@replaceChrome 完全対応 50Edge 完全対応 79Firefox 完全対応 49IE 未対応 なしOpera 完全対応 37Safari 完全対応 10WebView Android 完全対応 50Chrome Android 完全対応 50Firefox Android 完全対応 49Opera Android 完全対応 37Safari iOS 完全対応 10Samsung Internet Android 完全対応 5.0nodejs 完全対応 6.0.0

凡例

完全対応  
完全対応
未対応  
未対応

関連項目