Array : mthode copyWithin()

Exemple interactif

const array = ["a", "b", "c", "d", "e"];

// Copie  l'indice 0 l'lment  l'indice 3
console.log(array.copyWithin(0, 3, 4));
// Rsultat attendu : Array ["d", "b", "c", "d", "e"]

// Copie  l'indice 1 tous les lments de l'indice 3  la fin
console.log(array.copyWithin(1, 3));
// Rsultat attendu : Array ["d", "d", "e", "d", "e"]

Syntaxe

copyWithin(target, start)
copyWithin(target, start, end)

Paramtres

target

L'indice ( partir de zro) auquel copier la squence, converti en entier. Cela correspond l'emplacement o l'lment l'indice start sera copi, et tous les lments compris entre start et end seront copis aux indices suivants.

• Un indice ngatif compte rebours depuis la fin du tableau si -array.length <= target < 0, on utilise target + array.length.
• Si target < -array.length, on utilise 0.
• Si target >= array.length, rien n'est copi.
• Si target est positionn aprs start aprs normalisation, la copie ne se fait que jusqu' la fin de array.length (autrement dit, copyWithin() n'tend jamais le tableau).

start

L'indice ( partir de zro) partir duquel commencer copier les lments, converti en entier.

• Un indice ngatif compte rebours depuis la fin du tableau si -array.length <= start < 0, on utilise start + array.length.
• Si start < -array.length, on utilise 0.
• Si start >= array.length, rien n'est copi.

end Facultatif

L'indice ( partir de zro) auquel arrter de copier les lments, converti en entier. copyWithin() copie jusqu' (mais sans inclure) end.

• Un indice ngatif compte rebours depuis la fin du tableau si -array.length <= end < 0, on utilise end + array.length.
• Si end < -array.length, on utilise 0.
• Si end >= array.length ou si end est omis ou undefined, on utilise array.length, ce qui fait que tous les lments jusqu' la fin sont copis.
• Si end implique une position avant ou la mme position que celle implique par start, rien n'est copi.

Valeur de retour

Le tableau modifi.

Description

La mthode copyWithin() fonctionne comme memmove en C et C++ ; c'est une mthode trs performante pour dcaler les donnes d'un tableau (Array). Cela s'applique en particulier la mthode TypedArray du mme nom. La squence est copie et colle en une seule opration ; la squence colle aura les valeurs copies mme si les zones de copie et de collage se chevauchent.

Comme undefined devient 0 lorsqu'il est converti en entier, omettre le paramtre start a le mme effet que de passer 0, ce qui copie tout le tableau la position cible, quivalent un dcalage vers la droite o la borne droite est tronque et la borne gauche est duplique. Ce comportement peut prter confusion pour les lecteursrices de votre code ; il est donc prfrable de passer explicitement 0 comme valeur de start.

console.log([1, 2, 3, 4, 5].copyWithin(2));
// [1, 2, 1, 2, 3] ; dcale tous les lments de 2 positions vers la droite

La mthode copyWithin() est une mthode de mutation. Elle ne modifie pas la longueur de this, mais elle modifie le contenu de this et peut crer de nouvelles proprits ou supprimer des proprits existantes si ncessaire.

La mthode copyWithin() prserve les cases vides. Si la rgion copier est creuxe, les nouveaux indices correspondants des cases vides sont supprims et deviennent aussi des cases vides.

La mthode copyWithin() est gnrique. Elle attend seulement que la valeur de this possde une proprit length et des proprits cls entires. Bien que les chanes de caractres soient aussi similaires des tableaux, cette mthode n'est pas adapte pour tre applique sur elles, car les chanes sont immuables.

Exemples

Utilisation de copyWithin()

console.log([1, 2, 3, 4, 5].copyWithin(0, 3));
// [4, 5, 3, 4, 5]

console.log([1, 2, 3, 4, 5].copyWithin(0, 3, 4));
// [4, 2, 3, 4, 5]

console.log([1, 2, 3, 4, 5].copyWithin(-2, -3, -1));
// [1, 2, 3, 3, 4]

Utilisation de copyWithin() sur des tableaux creux

copyWithin() propage les cases vides.

console.log([1, , 3].copyWithin(2, 1, 2)); // [1, vide, vide]

Appel de copyWithin() sur des objets qui ne sont pas des tableaux

La mthode copyWithin() lit la proprit length de this puis manipule les indices entiers concerns.

const objetSimilaireTableau = {
  length: 5,
  3: 1,
};
console.log(Array.prototype.copyWithin.call(objetSimilaireTableau, 0, 3));
// { '0': 1, '3': 1, length: 5 }
console.log(Array.prototype.copyWithin.call(objetSimilaireTableau, 3, 1));
// { '0': 1, length: 5 }
// La proprit '3' est supprime car la source copie est une case vide

Spcifications

Compatibilit des navigateurs

Voir aussi

• Guide des collections indexes
• L'objet global Array
• La mthode TypedArray.prototype.copyWithin()
• Prothse d'mulation de Array.prototype.copyWithin dans core-js(angl.)
• Prothse d'mulation es-shims de Array.prototype.copyWithin(angl.)