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.
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.
copyWithin(target, start) copyWithin(target, start, end)
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.
target < 0
, target + array.length
is used.target < -array.length
, 0
is used.target >= array.length
, nothing is copied.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.
start < 0
, start + array.length
is used.start < -array.length
, 0
is used.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
.
end < 0
, end + array.length
is used.end < -array.length
, 0
is used.end >= array.length
or end
is omitted, array.length
is used, causing all elements until the end to be copied.end
is positioned before or at start
after normalization, nothing is copied.The modified array.
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.
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]
copyWithin()
will propagate empty slots.
console.log([1, , 3].copyWithin(2, 1, 2)); // [1, empty, empty]
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
Desktop | Mobile | Server | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android | Deno | Node.js | ||
copyWithin |
45 | 12 | 32 | 32 | 9 | 45 | 32 | 32 | 9 | 5.0 | 45 | 1.0 | 4.0.0 |
© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/copyWithin