Array.prototype.copyWithin()

Try it

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

// Copy to index 0 the element at index 3
console.log(array.copyWithin(0, 3, 4));
// Expected output: Array ["d", "b", "c", "d", "e"]

// Copy to index 1 all elements from index 3 to the end
console.log(array.copyWithin(1, 3));
// Expected output: Array ["d", "d", "e", "d", "e"]

Syntax

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

Parameters

target

Zero-based index at which to copy the sequence to, converted to an integer. This corresponds to where the element at start will be copied to, and all elements between start and end are copied to succeeding indices.

• Negative index counts back from the end of the array — if -array.length <= 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

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 -array.length <= start < 0, start + array.length is used.
• If start < -array.length, 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 -array.length <= end < 0, end + array.length is used.
• If end < -array.length, 0 is used.
• If end >= array.length or end is omitted or undefined, array.length is used, causing all elements until the end to be copied.
• If end implies a position before or at the position that start implies, 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.

Because undefined becomes 0 when converted to an integer, omitting the start parameter has the same effect as passing 0, which copies the entire array to the target position, equivalent to a right shift where the right boundary is clipped off and the left boundary is duplicated. This behavior may confuse readers of your code, so you should explicitly pass 0 as start instead.

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

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(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

Browser compatibility

See also

• Polyfill of Array.prototype.copyWithin in core-js
• es-shims polyfill of Array.prototype.copyWithin
• Indexed collections guide
• Array
• TypedArray.prototype.copyWithin()