Array.prototype.toSpliced()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since 2023年7月.

toSpliced() は Array インスタンスのメソッドで、 splice() メソッドに対応するコピーメソッドです。これは、指定された位置の要素を除去したり置き換えたりした新しい配列を返します。

構文

js
toSpliced(start)
toSpliced(start, skipCount)
toSpliced(start, skipCount, item1)
toSpliced(start, skipCount, item1, item2)
toSpliced(start, skipCount, item1, item2, /* …, */ itemN)

引数

start

配列の変更を始める位置のゼロから始まるインデックスで、整数に変換されます。

負のインデックスは配列の末尾から数えます。 -array.length <= start < 0 の場合は start + array.length を使用します。
start < -array.length または start が省略された場合は 0 が使用されます。
start >= array.length である場合、削除される要素はありませんが、このメソッドは追加関数として動作し、提供されただけの要素を追加します。

skipCount 省略可

整数で、配列内で start から削除（またはスキップ）する要素の数を示します。

skipCount を省略した場合、またはその値が start で指定した位置以降の要素数以上の場合、 start から配列の末尾までのすべての要素が削除されます。ただし、もし itemN 引数を渡したい場合は、 Infinity を skipCount に渡して start 以降の要素をすべて削除してください。明示的に undefined を指定すると 0 に変換されてしまうからです。

skipCount が 0 または負の場合、要素は除去されません。この場合、少なくとも 1 つの新しい要素を指定する必要があります（下記参照）。

item1, …, itemN 省略可

配列に追加する要素を start から始めます。

要素を指定しない場合、 toSpliced() は配列から要素を取り除くだけです。

返値

start より前のすべての要素、 item1, item2, …, itemN と、 start + skipCount 以降のすべての要素からなる新しい配列です。

解説

toSpliced() メソッドは splice() と同様に、一度に複数のことを行います。指定されたインデックスの位置から、指定された数の要素を配列から除去し、同じインデックスの位置に指定された要素を挿入します。しかし、元の配列を変更するのではなく、新しい配列を返します。したがって、削除された要素は、このメソッドからは返されませんが、元の配列では引き続きアクセス可能です。

toSpliced() メソッドは決して疎配列を生成しません。疎配列の場合、空のスロットは新しい配列の undefined に置き換わります。

toSpliced() メソッドは汎用です。 this の値が length プロパティを持っており、整数のキーのプロパティがあることのみを期待します。

例

要素の削除、追加、置き換え

toSpliced() を使用すると、配列の要素を削除、追加、置き換えることができ、slice() や concat() を使用するよりも効率的に新しい配列を作成することができます。

js
const months = ["Jan", "Mar", "Apr", "May"];

// インデックス 1 の要素の挿入
const months2 = months.toSpliced(1, 0, "Feb");
console.log(months2); // ["Jan", "Feb", "Mar", "Apr", "May"]

// インデックス 2 から始まる 2 つの要素を削除
const months3 = months2.toSpliced(2, 2);
console.log(months3); // ["Jan", "Feb", "May"]

// インデックス 1 の要素を 2 つの新しい要素で置き換え
const months4 = months3.toSpliced(1, 1, "Feb", "Mar");
console.log(months4); // ["Jan", "Feb", "Mar", "May"]

// 元配列は変更しない
console.log(months); // ["Jan", "Mar", "Apr", "May"]

疎配列に対する toSpliced() の使用

toSpliced() メソッドは常に密な配列を作成します。

js
const arr = [1, , 3, 4, , 6];
console.log(arr.toSpliced(1, 2)); // [1, 4, undefined, 6]

配列以外のオブジェクトに対する toSpliced() の呼び出し

toSpliced() メソッドは this の length プロパティを読み取ります。そして、必要な整数キーのプロパティを読み込み、新しい配列に書き込みます。

js
const arrayLike = {
  length: 3,
  unrelated: "foo",
  0: 5,
  2: 4,
};
console.log(Array.prototype.toSpliced.call(arrayLike, 0, 1, 2, 3));
// [2, 3, undefined, 4]