JavaScript - copyWithin() method

revision:


Category : array

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

It copies array elements to another position in the array and overwrites the existing values. It does not add items to the array.

Syntax :

        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 : 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.

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.

Examples:

            const array1 = ['a', 'b', 'c', 'd', 'e'];
            // Copy to index 0 the element at index 3
            console.log(array1.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(array1.copyWithin(1, 3));
            // Expected output: Array ["d", "d", "e", "d", "e"]
        

Practical examples

example: using copyWithin() method

code:
                    <div>
                        <p id="copy-1"></p>
                        <p id="copy-2"></p>
                        <p id="copy-3"></p>
                        <p id="copy-4"></p>
                        <p id="copy-5"></p>
                        <p id="copy-6"></p>
                    </div>
                    <script>
                        const arr1 = [1, 2, 3, 4, 5];
                        document.getElementById('copy-1').innerHTML = "original array: " + arr1;
                        console.log([1, 2, 3, 4, 5].copyWithin(0, 3));
                        // [4, 5, 3, 4, 5]
                        document.getElementById("copy-2").innerHTML = ("arr1.copyWithin(0, 3) : " + arr1.copyWithin(0,3));
                        const arr2 = [6, 7, 8, 9, 10];
                        document.getElementById('copy-3').innerHTML = "original array: " + arr2;
                        console.log([6, 7, 8, 9, 10].copyWithin(0, 3, 4));
                        // [9, 7, 8, 9, 10]
                        document.getElementById("copy-4").innerHTML =  ("arr2.copyWithin(0, 3, 4) : " +arr2.copyWithin(0, 3, 4));
                        const arr3 = [2, 4, 6, 8, 10]
                        document.getElementById('copy-5').innerHTML = "original array: " + arr3;
                        console.log([2, 4, 6, 8, 10].copyWithin(-2, -3, -1));
                        // [2, 4, 6, 6, 8]
                        document.getElementById("copy-6").innerHTML =  ("arr3.copyWithin(-2, -3, -1) : " +arr3.copyWithin(-2, -3, -1));
                    </script>
                

example: using copyWithin() on sparse arrays

code:
                    <div>
                        <p id="copy-7"></p>
                        <p id="copy-8"></p>
                    </div>
                    <script>
                        const arr4 = [1, , 3];
                        console.log([1, , 3].copyWithin(2, 1, 2)); // [1, empty, empty]
                        document.getElementById('copy-7').innerHTML = "original array: " + arr4;
                        document.getElementById('copy-8').innerHTML = "copyWithin(2, 1, 2): " + arr4.copyWithin(2, 1, 2); 
            
                    </script>
                

example: copyWithin() copies array elements to another position in an array, overwriting existing values.

code:
                    <div>
                        <p id="copy-9"></p>
                        <p id="copy-10"></p>
                    </div>
                    <script>
                        const fruits = ["Banana", "Orange", "Apple", "Mango"];
                        document.getElementById("copy-9").innerHTML = "original array : " + fruits;
                        document.getElementById("copy-10").innerHTML = "copied array : " + fruits.copyWithin(2,0);
                    </script>