String.prototype.replace()

replace() メソッドは、pattern にマッチした文字列の一部または全てを replacement で置き換えた新しい文字列を返します。pattern は文字列または RegExp、replacement は文字列または各マッチで呼び出される関数です。

構文

str.replace(pattern, replacement[, flags])

引数

pattern

文字列 または RegExp オブジェクト です。マッチすると、第2引数の replacement と置き換えられます。

replacement

第一引数でマッチした箇所を置き換える 文字列 または 新しい部分文字列を生成するために実行される関数 を指定することができます。

flags  

• String.prototype.replace() のflags 引数は v8 Core (Chrome や Node.js) では機能しない非標準の仕様です。この引数を利用する代わりに、patternに /apple/gi といったフラグを伴った RegExp オブジェクトを利用する方法が一般的です。
• 正規表現のフラグの組み合わせを指定する文字列。この引数を使用する場合、その値は以下で述べる各作用を及ぼす文字のうち1文字以上からなる文字列である必要があります。

g	グローバルマッチ
i	大文字と小文字の違いを無視する
m	複数行を越えたマッチ
y	sticky

戻り値

パターンにマッチした部分文字列の一部または全てを置換文字列で置き換えた新しい文字列。

詳細

このメソッドは、それを呼び出した String オブジェクトを変化させません。戻り値として新しい文字列を返します。

グローバルな検索と置換を動作させるためには、正規表現に g フラグを含めるか、第一引数が文字列である場合には flags 引数に g を含める必要があります。

引数としての文字列の指定

置換文字列には以下の特殊な置換パターンを含めることができます。

引数としての関数の指定

第二引数として関数を指定することができます。このとき、関数はマッチが完了された後に実行されます。関数呼び出しの結果（返り値）は、置換文字列として使われます（注記: 上記の特殊な置換パターンはこの場合には適用されません）。第一引数の正規表現がグローバルだと、置換されるべきマッチごとに関数が複数回実行されうることに注意してください。

関数に与えられる引数は次の通りです。

（引数の正確な個数は、第一引数が RegExp オブジェクトかどうか、そうならばさらに括弧でキャプチャされるサブマッチがいくつ指定されているかに依ります。）

以下の例は newString に 'abc - 12345 - #$*%' をセットします。

function replacer(match, p1, p2, p3, offset, string) {
  // p1 is nondigits, p2 digits, and p3 non-alphanumerics
  return [p1, p2, p3].join(' - ');
}
var newString = 'abc12345#$*%'.replace(/([^\d]*)(\d*)([^\w]*)/, replacer);

例

正規表現を利用する

以下の例では、replace メソッドで正規表現を利用しています。

var str = "Twas the night before Xmas...";
var newstr = str.replace(/Xmas/, "Christmas");
console.log(newstr); // "Twas the night before Christmas..." 

ignore フラグとglobal フラグの利用

以下の例では、正規表現で大文字と小文字の違いを無視するフラグ (i) とグローバルマッチのフラグ (g)を利用しています。iフラグのみの場合、大文字小文字を無視したマッチした1つ目の文字列を置き換え、gフラグを加えるとマッチした全ての文字列を置き換える結果となります。

var str = "Apples are round, and apples are juicy.";

// i flag

var reg = /apples/i; 
var newstr = str.replace(reg, "oranges");
console.log(newstr);  // oranges are round, and apples are juicy.

// g + i flag

var reg = /apples/gi; //global flag
var newstr = str.replace(reg, "oranges");
console.log(newstr);  // oranges are round, and oranges are juicy.

文字列内の単語の交換

文字列内の単語の位置を交換します。$1 と $2 を置き換えるパターンを使用しています。

var re = /(\w+)\s(\w+)/;
var str = "John Smith";
var newstr = str.replace(re, "$2, $1");
console.log(newstr);  // Smith, John

マッチした文字を修正するインライン関数の使用

次の例では、文字列内に出現する大文字の全ては小文字に変換され、ハイフンがマッチした位置の直前に挿入されます。ここで重要なことは、追加の操作は、マッチしたアイテムが置換されて戻される前に必要とされるということです。

置換する関数はマッチした断片をその関数の引数として適用します。そして、その引数を大文字小文字変形し、戻り値の直前にハイフンを連結します。

function styleHyphenFormat(propertyName) {
  function upperToHyphenLower(match) {
    return '-' + match.toLowerCase();
  }
  return propertyName.replace(/[A-Z]/, upperToHyphenLower);
}

alert( styleHyphenFormat('borderTop') ); // "border-top" と出力されます。

最終的な置換が作成される前にサブマッチの結果 をさらに変形したい場合、関数を使わなくてはなりません。これは、toLowerCase() メソッドの前にマッチを評価することを強制します。関数無しにこれをマッチに使用した場合、その toLowerCase() メソッドは効果がないでしょう。

var newString = propertyName.replace(/[A-Z]/, '-' + '$&'.toLowerCase());  // 動作しないでしょう

これは、'$&'.toLowerCase() は、まずその文字がパターンとして使用される前に ('$&' という結果である ) 文字列リテラルとして評価されるだろうからです。

華氏温度を同等の摂氏温度と置き換える

以下の例は、ある華氏温度をそれと同等の摂氏温度と置き換えます。その華氏温度は F で終わる数でなければなりません。その関数は C で終わる摂氏を返します。例えば、入力される数が 212F である場合、その関数は 100C を返します。入力される数が 0F であった場合、その関数は -17.77777777777778C を返します。

その正規表現 test は、任意の数が F で終わっているかチェックします。華氏温度の数は、関数の 第二引数 p1 を通して、その関数にアクセスできます。その関数は文字列内で渡された華氏温度をベースとした摂氏の数を f2c にセットします。それから、f2c は、摂氏の数を返します。この関数は Perl の s///e フラグ 【訳注: s は substitute （置換する）の略。e は evaluate（評価する）の略です。詳細は perlop の Regexp Quote-Like Operators の項（※perldoc.jp による日本語訳）を参照してください。】 と似ています。

function f2c(x) {
  function convert(str, p1, offset, s) {
    return ((p1-32) * 5/9) + "C";
  }

  var s = String(x);
  var test = /(\d+(?:\.\d*)?)F\b/g;

  return s.replace(test, convert);
}

仕様

ブラウザ実装状況

Firefox 固有の注記

• Gecko 27 (Firefox 27 / Thunderbird 27 / SeaMonkey 2.24) 以降、このメソッドは ECMAScript 標準に準拠するために補正されました。replace() がグローバルの正規表現とともに呼び出された場合、RegExp.lastIndex プロパティが（もし指定されていたなら）0 にリセットされます (バグ 501739)。
• Gecko 39 (Firefox 39 / Thunderbird 39 / SeaMonkey 2.36) 以降、flags 引数は非推奨となり、コンソールに警告を投げます (バグ 1142351)。

参照

• String.prototype.match()
• RegExp.prototype.exec()
• RegExp.prototype.test()