Array : méthode with()

Syntaxe

arrayInstance.with(index, value)

Paramètres

index

Indice (à partir de zéro) à modifier dans le tableau, converti en entier.

• Un indice négatif compte à rebours depuis la fin du tableau — si -array.length <= index < 0, index + array.length est utilisé.
• Si l'indice après normalisation est hors limites, une exception RangeError est levée.

value

Toute valeur à affecter à l'indice donné.

Valeur de retour

Un nouveau tableau dans lequel l'élément à index est remplacé par value.

Exceptions

RangeError

Levée si index >= array.length ou index < -array.length.

Description

La méthode with() modifie la valeur à un indice donné dans le tableau, en retournant un nouveau tableau dans lequel l'élément à cet indice est remplacé par la valeur fournie. Le tableau d'origine n'est pas modifié. Cela permet d'enchaîner les méthodes de tableau lors des manipulations.

En combinant with() avec at(), vous pouvez lire et écrire (respectivement) dans un tableau en utilisant des indices négatifs.

La méthode with() ne produit jamais de tableau creux. Si le tableau source est creux, les cases vides seront remplacées par undefined dans le nouveau tableau.

La méthode with() est générique. Elle attend seulement que la valeur de this possède une propriété length et des propriétés à indices entiers.

Exemples

Créer un nouveau tableau avec un seul élément modifié

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

Méthodes de tableau chaînées

Avec la méthode with(), vous pouvez mettre à jour un élément d'un tableau puis appliquer d'autres méthodes de tableau.

const arr = [1, 2, 3, 4, 5];
console.log(arr.with(2, 6).map((x) => x ** 2)); // [1, 4, 36, 16, 25]

Utilisation de with() sur des tableaux creux

La méthode with() crée toujours un tableau dense.

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

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

La méthode with() crée et retourne un nouveau tableau. Elle lit la propriété length de this puis accède à chaque propriété dont la clé est un entier non négatif inférieur à length. À chaque accès, l'élément du tableau à l'indice correspondant est défini à la valeur de la propriété. Enfin, la valeur à index est définie à value.

const arrayLike = {
  length: 3,
  unrelated: "foo",
  0: 5,
  2: 4,
  3: 3, // ignoré par with() car length vaut 3
};
console.log(Array.prototype.with.call(arrayLike, 0, 1));
// [ 1, undefined, 4 ]

Spécifications

Compatibilité des navigateurs

Voir aussi

• Guide des collections indexées
• La méthode Array.prototype.toReversed()
• La méthode Array.prototype.toSorted()
• La méthode Array.prototype.toSpliced()
• La méthode Array.prototype.at()
• La méthode TypedArray.prototype.with()
• Prothèse d'émulation de Array.prototype.with dans core-js ^(angl.)
• Prothèse d'émulation es-shims de Array.prototype.with ^(angl.)