Array.prototype.unshift()

Baseline 広く利用可能

この機能は広く実装されており、多くのバージョンの端末やブラウザーで動作します。2015年7月以降、すべてのブラウザーで利用可能です。

unshift() は Array インスタンスのメソッドで、指定された要素を配列の先頭に追加し、新しい配列の長さを返します。

試してみましょう

const array = [1, 2, 3];

console.log(array.unshift(4, 5));
// 予想される結果: 5

console.log(array);
// 予想される結果: Array [4, 5, 1, 2, 3]

構文

js
unshift()
unshift(element1)
unshift(element1, element2)
unshift(element1, element2, /* …, */ elementN)

引数

element1, …, elementN

arr の先頭に追加する要素。

返値

メソッドを呼び出した後のオブジェクトの新しい length プロパティの値です。

解説

unshift() メソッドは、与えられた要素を配列風オブジェクトの一番最初に挿入します。

Array.prototype.push() は unshift() と似た動作をしますが、配列の末尾に対して行う点が異なります。

複数の要素が引数として渡された場合、引数として渡されたものと全く同じ順番で、オブジェクトの最初のチャンクに挿入されることに注意してください。したがって、 unshift() を n 個の引数で 1 回呼び出すのと、1 個の引数で n 回（例えばループを使って）呼び出すのとでは同じ結果にはなりません。

例をご覧ください。

js
let arr = [4, 5, 6];

arr.unshift(1, 2, 3);
console.log(arr);
// [1, 2, 3, 4, 5, 6]

arr = [4, 5, 6]; // 配列をリセット

arr.unshift(1);
arr.unshift(2);
arr.unshift(3);

console.log(arr);
// [3, 2, 1, 4, 5, 6]

unshift() メソッドは汎用的です。このメソッドは this 値に length プロパティと整数キーのプロパティがあることだけを期待します。文字列も配列風ですが、文字列は不変なので、このメソッドを適用するのには適していません。

例

unshift の使用

js
const arr = [1, 2];

arr.unshift(0); // 呼び出しの返値は 3、新しい配列の長さ
// arr is [0, 1, 2]

arr.unshift(-2, -1); // 新しい配列の長さは 5
// arr is [-2, -1, 0, 1, 2]

arr.unshift([-4, -3]); // 新しい配列の長さは 6
// arr is [[-4, -3], -2, -1, 0, 1, 2]

arr.unshift([-7, -6], [-5]); // 新しい配列の長さは 8
// arr is [ [-7, -6], [-5], [-4, -3], -2, -1, 0, 1, 2 ]

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

unshift() メソッドは this の length プロパティを読み込みます。 0 から length - 1 までの範囲にあるすべてのインデックスを、引数の数だけ右にシフトします（この数だけ値を増加します）。次に、 0 から始めるには、各インデックスを unshift() に渡した引数で設定します。最後に、length を前回の長さに、前に追加した要素の数を加えた値に設定します。

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

const plainObj = {};
// length プロパティがないため、 length は 0
Array.prototype.unshift.call(plainObj, 1, 2);
console.log(plainObj);
// { '0': 1, '1': 2, length: 2 }