MDN’s new design is in Beta! A sneak peek: https://blog.mozilla.org/opendesign/mdns-new-design-beta/

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

仕様

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

ブラウザ実装状況

機能 Chrome Firefox (Gecko) Internet Explorer Opera Safari
基本サポート ? 49 (49) ? ? ?
機能 Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
基本サポート ? ? 49.0 (49) ? ? ?

関連項目

ドキュメントのタグと貢献者

 このページの貢献者: YuichiNukiyama
 最終更新者: YuichiNukiyama,