.replace()

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace

パターンにマッチした一部または全ての文字列を、置換処理によって書き換えた新しい文字列を返します。パターンには文字列またはRegExpを使用することが可能です。また置換処理には文字列、または各マッチで呼び出される関数を指定することが可能です。

文法

str.replace(regexp|substr, newSubStr|function[, flags]);

置換処理によって、パターンにマッチした一部または全てが書き換えられた新しい文字列が返されます。

引数	説明
1つ目の引数(下記のいずれか)
regexp	型：RegExp RegExp(正規表現)オブジェクトを指定します。マッチした文字列は、2つ目の引数の値(文字列、または関数による戻り値)によって置換されます。
substr	型：String `newSubStr`に置き換えられる文字列を指定します。
2つ目の引数(下記のいずれか)
newSubStr	型：`String` 置き換える文字列を指定します。サポートされている幾つかの特別な置換パターンについて、後述する「引数として文字列を指定」を参照してください。
function	新しい部分文字列を作成するために実行される関数を指定します。 (1つ目の引数から受け取った部分文字列と置き換えるための) この関数に提供される引数については、後述する「引数として関数を指定」の中で説明されています。
3つ目の引数(任意)
flags 非標準	型：`String` 正規表現フラグ(flags)との連携を指示する文字列を指定します。 String.replaceメソッドでのフラグの使用は非標準です。そのため、代わりにRegExpオブジェクトとそれに対応するフラグを使用するのが良いかもしれません。この引数の値は、下記の文字の1文字または複数文字で構成される必要があり、正規表現の動作にどのような作用を与えるのかを指定します。 g グローバルマッチ(最初に見つかったマッチだけでなく全てにマッチ)します。 i 大文字・小文字の違いを無視します。 m 行をまたいでマッチします。 y (experimental) sticky

説明

このメソッドは、呼び出し元の文字列を変更しません。ただ単純に新しい文字列を返すだけです。

グローバル(global)の検索と置換の実行するためには、正規表現内にgの切り替えを含めるか、 1つ目の引数が文字列であれば、flag引数にgを含めます。

引数として文字列を指定

置換する文字列には、下記の特別な置換パターンを含めることが可能です。

パターン	挿入文字列
`$$`	"$"文字が挿入されます。
`$&`	マッチした文字列部分を挿入します。
$`	マッチした部分文字列の前にある文字列を挿入します。
`$'`	マッチした部分文字列の後ろに続く文字列を挿入します。
`$n` または`$nn`	nまたはnnの部分には数値桁が入り、このメソッドの1つ目の引数がRegExpオブジェクトで提供された際の、 `n`番目の丸括弧の部分マッチ文字列が挿入されます。

引数として関数を指定

2つ目の引数として、関数を指定することが可能で、このケースではマッチが実行された後にその関数が実行されます。関数の結果(戻り値)は、置換文字列として使用されます。 (注意: 前述した特別な置換パターンは、このケースでは適用されません。) もし1つ目の引数の正規表現がグローバル指定されている場合、全てのマッチへの置換の数だけ、関数が実行されることに注意してください。

関数に渡すことが出来る引数は下記の通りです。

指定可能な名前	提供される値
match	マッチした文字列部分です。 (前述の`$&`に相当)
p1, p2, ...	置換対象を指定する1つ目の引数にRegExpオブジェクトが提供された際の、丸括弧指定された`n`番目の部分文字列です。 (前述の`$1`、`$2`...`$n`に相当) 例えば、正規表現`/(\a+)(\b+)/`が渡された場合、 p1は`\a+`に、p2は`\b+`にマッチしたものになります。
offset	マッチした部分文字列の、対象としている文字列全体でのオフセットになります。 (例えば、文字列全体が"abcd"であり、マッチした部分文字列が"bc"だったとすると、この引数は1になります。)
string	対象となる文字列全体です。

(引数の正確な数は、1つ目の引数がRegExpオブジェクトであるか、またそうであるならば、丸括弧によるサブマッチ指定が幾つあるのかに依存します。)

下記の例は結果として、newStringには、 "abc - 12345 - #$*%"がセットされます。

function replacer(match, p1, p2, p3, offset, string){
  // p1には数値以外の文字、
  // p2には数値、
  // p3には数値とアルファベット以外の文字が格納されます。
  return [p1, p2, p3].join(' - ');
}
newString = "abc12345#$*%".replace(/([^\d]*)(\d*)([^\w]*)/, replacer);

例

例: 置換にglobal(グローバル)とigonore(無視)を使用

下記の例は、正規表現にglobalとigonoreフラグが含まれているため、 replaceは文字列内に存在する各'apples'を'oranges'に置換することが出来ます。

var re = /apples/gi;
var str = "Apples are round, and apples are juicy.";
var newstr = str.replace(re, "oranges");
print(newstr);

下記の例では、 1つ目の引数には文字列が使用されており、globalとignoreのフラグは、flags引数として指定されています。

var str = "Apples are round, and apples are juicy.";
var newstr = str.replace("apples", "oranges", "gi");
print(newstr);

どちらの例も、"oranges are round, and oranges are juicy."を出力します。

例: replace内での正規表現の定義

下記の例では、正規表現はreplace内にigonoreフラグ付きで定義されています。

var str = "Twas the night before Xmas...";
var newstr = str.replace(/xmas/i, "Christmas");
print(newstr);

これは、"Twas the night before Christmas..."を出力します。

例: 文字列内の単語の入れ替え

下記のスクリプトは、文字列内の単語を入れ替えます。これを実現するために、$1と$2の置換パターンが使用されています。

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

これは、"Smith, John"を出力します。

例: マッチした文字を編集するインライン関数を使用

この例では、文字列内に存在する全ての頭文字は小文字に変換され、そのマッチした位置の前にハイフンを挿入します。ここで重要なのは、置換されたものが返される前に、追加の処理がマッチした項目に対して必要であるということです。

置換処理を行う関数は、引数としてマッチした断片部分を受け取り、返される前に小文字変換とハイフン連結処理を行います。

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

styleHyphenFormat('borderTop')が与えられた場合、'border-top'が返されます。

最終的な置換が行われる前にマッチした結果を更に変形させたいのであれば、関数を使用すべきです。これはtoLowerCase()メソッドに先立って、マッチの評価が実行されます。関数無しでマッチを使用してこれを行おうとしても、 toLowerCase()は動作しません。

// 動作しません。
var newString = propertyName.replace(/[A-Z]/g, '-' + '$&'.toLowerCase());

これはパターンとして文字が使用される前に、 '$&'.toLowerCase()が文字列リテラルとして先に評価(結果は同じ'$&'となります)されるためです。

例: 華氏温度を同じ摂氏温度に置換

下記は華氏温度を同じ摂氏温度に置換する例です。華氏温度は数値の最後にFを必要とし、この関数は摂氏温度の数値の最後にCを付けて返します。例えば、212Fを入力すると、この関数は100Cを返します。 0Fであれば、この関数は-17.77777777777778Cを返します。

正規表現testは、最後にFが付く数値であるかを調べます。摂氏温度の数値は、2つ目の引数であるp1を通して関数からアクセス可能になります。この関数はf2c関数へ文字列で渡された華氏温度をもとにして、摂氏温度を設定し、最終的にf2cが摂氏温度の数値を返します。この関数は、Perlのs/…/…/eのフラグの形式にほぼ相当します。

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);
}

例: ループ処理を避けるめにインライン関数を正規表現で使用

下記の例は文字列のパターンを取得して、オブジェクトの配列へ変換します。

入力: 文字x、-、_で作成された文字列

x-x_
x---x---x---x---
x-xxx-xx-x-
x_x_x___x___x___

出力: オブジェクトの配列です。 'x'は'on'の状態を示し、 '-'(ハイフン)は'off'(on: false)の状態を示し、 '_'(アンダースコア)は'on'状態の長さ(length)を示します。

[
  { on: true, length: 1 },
  { on: false, length: 1 },
  { on: true, length: 2 }
  ...
]

スニペット:

var str = 'x-x_';
var retArr = [];
str.replace(/(x_*)|(-)/g, function(match, p1, p2){
  if(p1) retArr.push({ on: true, length: p1.length });
  if(p2) retArr.push({ on: false, length: 1 });
});

console.log(retArr);

このスニペットはforループを使用せずに、望むフォーマットで3つのオブジェクトの配列を生成します。

仕様

ブラウザ互換性

デスクトップ
機能	Chrome	Firefox (Gecko)	IE	Opera	Safari
基本	◯	◯	◯	◯	◯

モバイル
機能	Android	Chrome for Android	Firefox Mobile	IE Mobile	Opera Mobile	Safari Mobile
基本	◯	◯	◯	◯	◯	◯