Array.prototype.copyWithin()

The copyWithin() method shallow copies part of an array to another location in the same array and returns it without modifying its length.

Try it

Syntax

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

Parameters

target

Zero-based index at which to copy the sequence to, converted to an integer.

  • Negative index counts back from the end of the array — if target < 0, target + array.length is used.
  • If target < -array.length, 0 is used.
  • If target >= array.length, nothing is copied.
  • If target is positioned after start after normalization, copying only happens until the end of array.length (in other words, copyWithin() never extends the array).
start Optional

Zero-based index at which to start copying elements from, converted to an integer.

  • Negative index counts back from the end of the array — if start < 0, start + array.length is used.
  • If start < -array.length or start is omitted, 0 is used.
  • If start >= array.length, nothing is copied.
end Optional

Zero-based index at which to end copying elements from, converted to an integer. copyWithin() copies up to but not including end.

  • Negative index counts back from the end of the array — if end < 0, end + array.length is used.
  • If end < -array.length, 0 is used.
  • If end >= array.length or end is omitted, array.length is used, causing all elements until the end to be copied.
  • If end is positioned before or at start after normalization, nothing is copied.

Return value

The modified array.

Description

The copyWithin() method works like C and C++'s memmove, and is a high-performance method to shift the data of an Array. This especially applies to the TypedArray method of the same name. The sequence is copied and pasted as one operation; the pasted sequence will have the copied values even when the copy and paste region overlap.

The copyWithin() method is a mutating method. It does not alter the length of this, but it will change the content of this and create new properties or delete existing properties, if necessary.

The copyWithin() method preserves empty slots. If the region to be copied from is sparse, the empty slots' corresponding new indices are deleted and also become empty slots.

The copyWithin() method is generic. It only expects the this value to have a length property and integer-keyed properties. Although strings are also array-like, this method is not suitable to be applied on them, as strings are immutable.

Examples

Using copyWithin()

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

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]

Using copyWithin() on sparse arrays

copyWithin() will propagate empty slots.

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

Calling copyWithin() on non-array objects

The copyWithin() method reads the length property of this and then manipulates the integer indices involved.

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

Specifications

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

Browser compatibility

BCD tables only load in the browser

See also