Array.prototype.copyWithin()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since ⁨setembro de 2015⁩.

O métodocopyWithin() copia parte de um array para outra localização no mesmo array e o retorna sem alterar seu tamanho.

Experimente

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

Sintaxe

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

Parâmetros

target

Índice de base zero à qual copiar a sequência para,convertido para inteiro.

Índice negativo será contado a partir do final do array — setarget < 0,target + array.length é utilizado.
Setarget < -array.length,0 é utilizado.
Setarget >= array.length, nada é copiado.
Setarget é posicionado apósstart depois da normalização, a cópia só acontece até o final doarray.length (em outras palavras,copyWithin() nunca estende o array).

startOptional

Índice de base zero à qual inicia a cópia dos elementos a partir de,convertido para inteiro.

Índice negativo será contado a partir do final do array — sestart < 0,start + array.length é utilizado.
Sestart < -array.length oustart é omitido,0 é utilizado.
Sestart >= array.length, nada é copiado.

endOptional

Índice de base zero à qual termina a cópia dos elementos a partir de,convertido para inteiro.copyWithin() copia até, mas não inclui oend.

Índice negativo será contado a partir do final do array — seend < 0,end + array.length é utilizado.
Seend < -array.length,0 é utilizado.
Seend >= array.length ouend é omitido,array.length é utilizado, fazendo com que todos os elementos até o final sejam copiados.
Seend é posicionado antes ou emstart após a normalização, nada será copiado.

O métodocopyWithin() funciona como omemmove do C e C++, e é um método de alta performance para troca de dados de umArray. Isso se aplica especialmente ao métodoTypedArray de mesmo nome. A sequência é copiada e colada como uma operação; a sequência colada terá os valores copiados mesmo quando a região de copiar e colar se sobrepuserem.

O métodocopyWithin() é ummétodo mutável. Ele não altera o comprimento dethis, mas mudará o conteúdo dethis e criará novas propriedades ou excluirá propriedades existentes, se necessário.

O métodocopyWithin() preserva slots vazios. Se a região a ser copiada forsparse, os novos índices correspondentes dos slots vazios sãoexcluídos e também se tornam slots vazios.

O métodocopyWithin() égenérico. Ele apenas espera que o valor dethis tenha uma propriedadelength e propriedades integer-keyed. Embora as strings também sejam semelhantes a arrays, esse método não é adequado para ser aplicado nelas, pois as strings são imutáveis.

Exemplos

Usando copyWithin()

console.log([1, 2, 3, 4, 5].copyWithin(-2));// [1, 2, 3, 1, 2]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]

Usando copyWithin() em arrays sparse

copyWithin() propagará slots vazios(empty).

console.log([1, , 3].copyWithin(2, 1, 2)); // [1, empty, empty]

Chamando copyWithin() em objetos não array

O métodocopyWithin() lê a propriedadelength dothis e então manipula os índices inteiros envolvidos.

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 }// A propriedade '3' é excluída porque a fonte copiada é um slot vazio.