Array : mthode unshift()

Exemple interactif

const array1 = [1, 2, 3];

console.log(array1.unshift(4, 5));
// Rsultat attendu : 5

console.log(array1);
// Rsultat attendu : Array [4, 5, 1, 2, 3]

Syntaxe

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

Paramtres

element1, , elementN

Les lments ajouter au dbut du tableau arr.

Valeur de retour

La nouvelle valeur de la proprit length du tableau sur lequel a t appele la mthode.

Description

La mthode unshift() insre les valeurs fournies au dbut d'un objet ressemblant un tableau.

La mthode Array.prototype.push() a un comportement similaire unshift(), mais s'applique la fin d'un tableau.

Veuillez noter que, si plusieurs lments sont passs en paramtres, ils sont insrs en bloc au dbut de l'objet, dans le mme ordre que celui dans lequel ils ont t passs en paramtres. Ainsi, appeler unshift() avec n arguments une fois, ou l'appeler n fois avec 1 argument (par exemple dans une boucle), ne donne pas le mme rsultat.

Exemple :

let arr = [4, 5, 6];

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

arr = [4, 5, 6]; // rinitialisation du tableau

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

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

La mthode unshift() est gnrique. Elle attend seulement que la valeur de this possde une proprit length et des proprits indices entiers. Bien qu'une chane de caractres soit aussi un objet ressemblant un tableau, cette mthode ne convient pas pour tre applique sur une chane de caractres, car elle est immuable.

Exemples

Utilisation de unshift()

const arr = [1, 2];

arr.unshift(0); // le rsultat de l'appel est 3, qui est la nouvelle longueur du tableau
// arr vaut [0, 1, 2]

arr.unshift(-2, -1); // la nouvelle longueur du tableau est 5
// arr vaut [-2, -1, 0, 1, 2]

arr.unshift([-4, -3]); // la nouvelle longueur du tableau est 6
// arr vaut [[-4, -3], -2, -1, 0, 1, 2]

arr.unshift([-7, -6], [-5]); // la nouvelle longueur du tableau est 8
// arr vaut [ [-7, -6], [-5], [-4, -3], -2, -1, 0, 1, 2 ]

Appeler unshift() sur des objets qui ne sont pas des tableaux

La mthode unshift() lit la proprit length de this. Elle dcale tous les indices dans la plage de 0 length - 1 vers la droite du nombre d'arguments (en incrmentant leurs valeurs de ce nombre). Ensuite, elle dfinit chaque indice partir de 0 avec les arguments passs unshift(). Enfin, elle dfinit la proprit length l'ancienne longueur plus le nombre d'lments ajouts au dbut.

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

const plainObj = {};
// Il n'y a pas de proprit length, donc la longueur est 0
Array.prototype.unshift.call(plainObj, 1, 2);
console.log(plainObj);
// { '0': 1, '1': 2, length: 2 }

Spcifications

Compatibilit des navigateurs

Voir aussi

• Guide des collections indexes
• L'objet natif Array
• La mthode Array.prototype.push()
• La mthode Array.prototype.pop()
• La mthode Array.prototype.shift()
• La mthode Array.prototype.concat()
• La mthode Array.prototype.splice()
• Prothse d'mulation de Array.prototype.unshift dans core-js (angl.)
• Prothse d'mulation es-shims de Array.prototype.unshift (angl.)