The copyWithin()
method of Array instances shallow copies part of this array to another location in the same array and returns this array without modifying its length.
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 betweenstart
andend
are copied to succeeding indices.- 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 afterstart
after normalization, copying only happens until the end ofarray.length
(in other words,copyWithin()
never extends the array).
- Negative index counts back from the end of the array — if
- : Zero-based index at which to copy the sequence to, converted to an integer. This corresponds to where the element at
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
start < 0
,start + array.length
is used. - If
start < -array.length
,0
is used. - If
start >= array.length
, nothing is copied.
- Negative index counts back from the end of the array — if
- : Zero-based index at which to start copying elements from, converted to an integer.
end
- : Zero-based index at which to end copying elements from, converted to an integer.
copyWithin()
copies up to but not includingend
.- 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
orend
is omitted,array.length
is used, causing all elements until the end to be copied. - If
end
is positioned before or atstart
after normalization, nothing is copied.
- Negative index counts back from the end of the array — if
- : Zero-based index at which to end copying elements from, converted to an integer.
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