Array.prototype.copyWithin()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2016.

Die copyWithin()-Methode von Array-Instanzen kopiert seicht einen Teil dieses Arrays an eine andere Stelle im gleichen Array und gibt dieses Array zurück, ohne seine Länge zu ändern.

Probieren Sie es aus

Syntax

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

Parameter

target

Nullbasierter Index, an dem die Sequenz kopiert wird, in eine Ganzzahl umgewandelt. Dies entspricht der Stelle, an die das Element von start kopiert wird, und alle Elemente zwischen start und end werden an nachfolgende Indizes kopiert.

  • Negative Indizes zählen vom Ende des Arrays zurück — wenn -array.length <= target < 0, wird target + array.length verwendet.
  • Wenn target < -array.length, wird 0 verwendet.
  • Wenn target >= array.length, wird nichts kopiert.
  • Wenn target nach der Normalisierung hinter start positioniert ist, wird nur bis zum Ende von array.length kopiert (mit anderen Worten, copyWithin() erweitert das Array nie).
start

Nullbasierter Index, von dem begonnen wird, Elemente zu kopieren, in eine Ganzzahl umgewandelt.

  • Negative Indizes zählen vom Ende des Arrays zurück — wenn -array.length <= start < 0, wird start + array.length verwendet.
  • Wenn start < -array.length, wird 0 verwendet.
  • Wenn start >= array.length, wird nichts kopiert.
end Optional

Nullbasierter Index, an dem das Kopieren der Elemente endet, in eine Ganzzahl umgewandelt. copyWithin() kopiert bis, aber nicht einschließlich end.

  • Negative Indizes zählen vom Ende des Arrays zurück — wenn -array.length <= end < 0, wird end + array.length verwendet.
  • Wenn end < -array.length, wird 0 verwendet.
  • Wenn end >= array.length oder end weggelassen wird, wird array.length verwendet, wodurch alle Elemente bis zum Ende kopiert werden.
  • Wenn end eine Position vor oder an der Position impliziert, die start impliziert, wird nichts kopiert.

Rückgabewert

Das modifizierte Array.

Beschreibung

Die copyWithin()-Methode funktioniert ähnlich wie C und C++'s memmove und ist eine hochperformante Methode, um die Daten eines Array zu verschieben. Dies gilt besonders für die Methode TypedArray mit dem gleichen Namen. Die Sequenz wird als ein Vorgang kopiert und eingefügt; die eingefügte Sequenz hat die kopierten Werte auch dann, wenn der Kopier- und Einfügebereich überlappen.

Da undefined beim Konvertieren in eine Ganzzahl zu 0 wird, hat das Weglassen des start-Parameters denselben Effekt, als würde 0 übergeben, was das gesamte Array an die Zielposition kopiert, was einem Rechtsschieben entspricht, bei dem die rechte Grenze abgeschnitten und die linke Grenze dupliziert wird. Dieses Verhalten kann Leser Ihres Codes verwirren, daher sollten Sie explizit 0 als start übergeben.

js
console.log([1, 2, 3, 4, 5].copyWithin(2));
// [1, 2, 1, 2, 3]; move all elements to the right by 2 positions

Die copyWithin()-Methode ist eine verändernde Methode. Sie verändert nicht die Länge von this, aber sie wird den Inhalt von this ändern und bei Bedarf neue Eigenschaften erstellen oder vorhandene löschen.

Die copyWithin()-Methode bewahrt leere Stellen. Wenn der zu kopierende Bereich lückenhaft ist, werden die entsprechenden neuen Indizes der leeren Stellen gelöscht und werden ebenfalls leere Stellen.

Die copyWithin()-Methode ist generisch. Sie erwartet nur, dass der this-Wert eine length-Eigenschaft und ganzzahlenschlüsselbasierte Eigenschaften hat. Obwohl Strings auch array-ähnlich sind, ist diese Methode nicht geeignet, um auf ihnen angewendet zu werden, da Strings unveränderlich sind.

Beispiele

Verwenden von copyWithin()

js
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]

Verwenden von copyWithin() auf lückenhaften Arrays

copyWithin() wird leere Stellen propagieren.

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

Aufrufen von copyWithin() auf Nicht-Array-Objekten

Die copyWithin()-Methode liest die length-Eigenschaft von this und manipuliert dann die beteiligten ganzzahligen Indizes.

js
const arrayLike = {
  length: 5,
  3: 1,
};
console.log(Array.prototype.copyWithin.call(arrayLike, 0, 3));
// { '0': 1, '3': 1, length: 5 }
console.log(Array.prototype.copyWithin.call(arrayLike, 3, 1));
// { '0': 1, length: 5 }
// The '3' property is deleted because the copied source is an empty slot

Spezifikationen

Specification
ECMAScript Language Specification
# sec-array.prototype.copywithin

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch