JavaScript Array copyWithin() Method

By Arvind Rai, September 18, 2019

The copyWithin() method of a JavaScript Array copies part of Array to another location in the same Array and returns it without modifying its length. Find the sample example. Find the syntax of copyWithin() method.

copyWithin(target,  start,  end)

The return value will be modified Array. Find the description of arguments.
target
1. Target index is the index at which to copy the sequence.
2. If target index is negative, then it will be counted from the end.
3. If target index is equal or greater than Array length, then nothing will be copied.
4. If target index is positioned after start index, then the copied sequence will be trimmed to fit Array length.

start
1. Start index is the index at which to start copying elements from.
2. If start index is negative, then it will be counted from the end.
3. If start index is omitted, then start index will be considered as 0.

end
1. End index is the index at which to end copying elements from.
2. Array elements are copied from start index up to end index but excluding value at end index.
3. If end index is negative, then end index will be counted from end.
4. If end index is omitted, then end index will be equal to length of the Array.

Example 1: Target index 0 or greater than 0
Example 2: Target index negative
Example 3: Target index equal or greater than Array length
Example 4: Target positioned after start index
Example 5: Start and end index 0 or greater than 0
Example 6: Start index negative
Example 7: Start and end index omitted
Example 8: End index negative
Reference

Example 1: Target index 0 or greater than 0

Find the examples with target index 0 or greater than 0.
1. copyWithin(0, 2, 4) : The sequence will be created from start index 2 up to end index 4. The element at end index is not included to create sequence. It means sequence will include elements of indexes 2 and 3. Then this sequence will be copied from target index 0. There will be no change in Array length.
2. copyWithin(1, 2, 4) : The sequence will be copied from target index 1.

Look into the below code snippet.

var numArray = [12, 13, 14, 15, 16, 17];
numArray.copyWithin(0, 2, 4);
console.log(numArray); //[ 14, 15, 14, 15, 16, 17 ]

copyWithin(0, 2, 4) has target index 0, start index 2 and end index 4. The sequence will be from index 2 to 3 excluding the element at end index. So the sequence will be 14, 15. This sequence will be copied starting from target index 0.
Find more examples.

var numArray = [12, 13, 14, 15, 16, 17];
numArray.copyWithin(1, 2, 5);
console.log(numArray); //[ 12, 14, 15, 16, 16, 17 ]

var planets = ['Jupiter', 'Earth', 'Mercury', 'Mars', 'Venus', 'Saturn'];
planets.copyWithin(2, 1, 4);
console.log(planets); //[ "Jupiter", "Earth", "Earth", "Mercury", "Mars", "Saturn" ]

In the number array, copyWithin(1, 2, 5) has target index 1, start index is 2 and end index 5. So the sequence will be 14, 15, 16 excluding element at end index. This sequence will be copied from target index 1.
In string array, copyWithin(2, 1, 4) has target index 2, start index 1 and end index 4. So the sequence will be 'Earth', 'Mercury', 'Mars'. This sequence will be copied from target index 2.

Example 2: Target index negative

When target index is negative, then it is counted from the end.
If target index is -1, then target index is array.length -1
If target index is -2, then target index is array.length -2
If target index is -3, then target index is array.length -3

var numArray = [12, 13, 14, 15, 16, 17];
numArray.copyWithin(-1, 2, 4);
console.log(numArray); //[ 12, 13, 14, 15, 16, 14 ]

numArray = [12, 13, 14, 15, 16, 17];
numArray.copyWithin(-2, 2, 4);
console.log(numArray); //[ 12, 13, 14, 15, 14, 15 ]

var planets = ['Jupiter', 'Earth', 'Mercury', 'Mars', 'Venus', 'Saturn'];
planets.copyWithin(-3, 2, 4);
console.log(planets); //[ "Jupiter", "Earth", "Mercury", "Mercury", "Mars", "Saturn" ]

Example 3: Target index equal or greater than Array length

If target index is equal or greater than Array length, then nothing will be copied and there will be no change in Array content. In our example, the array length is 6 and we are using target index as 6 and 8. We will see in output that there is no change in Array.

var numArray = [12, 13, 14, 15, 16, 17];
numArray.copyWithin(6, 2, 4);
console.log(numArray); //[ 12, 13, 14, 15, 16, 17 ]

numArray = [12, 13, 14, 15, 16, 17];
numArray.copyWithin(8, 2, 4);
console.log(numArray); //[ 12, 13, 14, 15, 16, 17 ]

var planets = ['Jupiter', 'Earth', 'Mercury', 'Mars', 'Venus', 'Saturn'];
planets.copyWithin(8, 2, 4);
console.log(planets); //[ "Jupiter", "Earth", "Mercury", "Mars", "Venus", "Saturn" ]

Example 4: Target positioned after start index

If target index is positioned after start index, then the copied sequence will be trimmed to fit Array length. In the below example, copyWithin(3, 1, 5) will try to copy the sequence 13, 14, 15, 16 starting from target index 3. The copied sequence will be trimmed to fit Array length and only sequence 13, 14, 15 will be copied.

var numArray = [12, 13, 14, 15, 16, 17];
numArray.copyWithin(3, 1, 5);
console.log(numArray); //[ 12, 13, 14, 13, 14, 15 ]

var planets = ['Jupiter', 'Earth', 'Mercury', 'Mars', 'Venus', 'Saturn'];
planets.copyWithin(4, 1, 5);
console.log(planets); //[ "Jupiter", "Earth", "Mercury", "Mars", "Earth", "Mercury" ]

Example 5: Start and end index 0 or greater than 0

Find the example when start and end index greater or equal to 0. In our below example we have copyWithin(2, 3, 5). In number array, the sequence 25, 26 will be copied from target index 2.

var numArray = [22, 23, 24, 25, 26, 27];
numArray.copyWithin(2, 3, 5);
console.log(numArray); //[ 22, 23, 25, 26, 26, 27 ]

var persons = ['Mohan', 'Sohan', 'Krishna', 'Shiva', 'Mahesh', 'Vishnu'];
persons.copyWithin(2, 3, 5);
console.log(persons); //[ "Mohan", "Sohan", "Shiva", "Mahesh", "Mahesh", "Vishnu" ]

Example 6: Start index negative

When start index is negative, then we count start index from end and actual start index will be (array.length –start index). If positive start index is greater that end index, then nothing will be copied.
We will observe following scenario in our below number array example.
copyWithin(2, -1, 3): Start index -1 will start from end and the index will be array.length -1 i.e. 5 and hence actual start index is 5 and end index is 3, so we will not get any sequence as start index is greater than end index.

copyWithin(2, -2, 3): As start index is -2 i.e. array.length-2 = 4 and end index is 3, and we can see that start index is greater than end index ,so nothing will be copied.

copyWithin(1, -4, 5): The start index is array.length - 4 = 2 and end index is 5, so sequence is 24, 25, 26 that will be copied in array from target index 1.

copyWithin(2, -3, 5): The start index is array.length - 3 = 3 and end index is 5, so sequence is 25, 26 that will be copied in array from target index 2.

var numArray = [22, 23, 24, 25, 26, 27];
numArray.copyWithin(1, -4, 5);
console.log(numArray); //[ 22, 24, 25, 26, 26, 27 ]

numArray = [22, 23, 24, 25, 26, 27];
numArray.copyWithin(2, -3, 5);
console.log(numArray); //[ 22, 23, 25, 26, 26, 27 ]

var persons = ['Mohan', 'Sohan', 'Krishna', 'Shiva', 'Mahesh', 'Vishnu'];
persons.copyWithin(2, -3, 4);
console.log(persons); //[ "Mohan", "Sohan", "Shiva", "Shiva", "Mahesh", "Vishnu" ]

Example 7: Start and end index omitted

When start index is omitted then start index is considered as 0 and when end index is omitted, then end index is considered as array.length. It means the sequence will be complete array. Sequence will be copied from given target index and will be trimmed to fit Array length.
Find the example when target index is +ve.

var numArray = [22, 23, 24, 25, 26, 27];
numArray.copyWithin(2);
console.log(numArray); //[ 22, 23, 22, 23, 24, 25 ]

Find the example when target index is -ve.

var numArray = [22, 23, 24, 25, 26, 27];
numArray.copyWithin(-2);
console.log(numArray); //[ 22, 23, 24, 25, 22, 23 ]

Example 8: End index negative

When end index is negative, then end index will be counted from end. The actual end index will be (array.length –end index).
In the number array in our below example, copyWithin(1, 2, -2) has end index as -2 i.e. array.length -2 = 4. So the start index is 2 and end index is 4 and hence sequence will be 24, 25 that will be copied from target index 1.

var numArray = [22, 23, 24, 25, 26, 27];
numArray.copyWithin(1, 2, -2);
console.log(numArray); //[ 22, 24, 25, 25, 26, 27 ]

var persons = ['Mohan', 'Sohan', 'Krishna', 'Shiva', 'Mahesh', 'Vishnu'];
persons.copyWithin(1, 2, -3);
console.log(persons); //[ "Mohan", "Krishna", "Krishna", "Shiva", "Mahesh", "Vishnu" ]