Array.prototype.toSpliced()
Baseline 2023
Newly available
Since July 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.
toSpliced()
は Array
インスタンスのメソッドで、 splice()
メソッドに対応するコピーメソッドです。これは、指定された位置の要素を除去したり置き換えたりした新しい配列を返します。
構文
toSpliced(start)
toSpliced(start, deleteCount)
toSpliced(start, deleteCount, item1)
toSpliced(start, deleteCount, item1, item2)
toSpliced(start, deleteCount, item1, item2, /* …, */ itemN)
引数
start
-
配列の変更を始める位置のゼロから始まるインデックスで、整数に変換されます。
- 負のインデックスは配列の末尾から数えます。
start < 0
の場合はstart + array.length
を使用します。 start < -array.length
またはstart
が省略された場合は0
が使用されます。start >= array.length
である場合、削除される要素はありませんが、このメソッドは追加関数として動作し、提供されただけの要素を追加します。
- 負のインデックスは配列の末尾から数えます。
deleteCount
省略可-
整数で、配列内で
start
から削除する要素の数を示します。deleteCount
を省略した場合、またはその値がstart
で指定した位置以降の要素数以上の場合、start
から配列の末尾までのすべての要素が削除されます。ただし、もしitemN
引数を渡したい場合は、Infinity
をdeleteCount
に渡してstart
以降の要素をすべて削除してください。明示的にundefined
を指定すると0
に変換されてしまうからです。deleteCount
が0
または負の場合、要素は除去されません。 この場合、少なくとも 1 つの新しい要素を指定する必要があります(下記参照)。 item1
, …,itemN
省略可-
配列に追加する要素を
start
から始めます。要素を指定しない場合、
toSpliced()
は配列から要素を取り除くだけです。
返値
start
, item1
, item2
, …, itemN
より前のすべての要素と、 start + deleteCount
より後のすべての要素からなる新しい配列です。
解説
toSpliced()
メソッドは splice()
と同様に、一度に複数のことを行います。指定されたインデックスの位置から、指定された数の要素を配列から除去し、同じインデックスの位置に指定された要素を挿入します。しかし、元の配列を変更するのではなく、新しい配列を返します。したがって、削除された要素はこのメソッドからは返されません。
toSpliced()
メソッドは決して疎配列を生成しません。疎配列の場合、空のスロットは新しい配列の undefined
に置き換わります。
toSpliced()
メソッドは汎用です。 this
の値が length
プロパティを持っており、整数のキーのプロパティがあることのみを期待します。
例
要素の削除、追加、置き換え
toSpliced()
を使用すると、配列の要素を削除、追加、置き換えることができ、slice()
や concat()
を使用するよりも効率的に新しい配列を作成することができます。
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()
メソッドは常に密な配列を作成します。
const arr = [1, , 3, 4, , 6];
console.log(arr.toSpliced(1, 2)); // [1, 4, undefined, 6]
配列以外のオブジェクトに対する toSpliced() の呼び出し
toSpliced()
メソッドは this
の length
プロパティを読み取ります。そして、必要な整数キーのプロパティを読み込み、新しい配列に書き込みます。
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]
仕様書
Specification |
---|
ECMAScript Language Specification # sec-array.prototype.tospliced |
ブラウザーの互換性
BCD tables only load in the browser