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étodo copyWithin() 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 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"]

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 — se target < 0, target + array.length é utilizado.
Se target < -array.length, 0 é utilizado.
Se target >= array.length, nada é copiado.
Se target é posicionado após start depois da normalização, a cópia só acontece até o final do array.length (em outras palavras, copyWithin() nunca estende o array).

start Optional

Í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 — se start < 0, start + array.length é utilizado.
Se start < -array.length ou start é omitido, 0 é utilizado.
Se start >= array.length, nada é copiado.

end Optional

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

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

O método copyWithin() funciona como o memmove do C e C++, e é um método de alta performance para troca de dados de um Array. Isso se aplica especialmente ao método TypedArray 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étodo copyWithin() é um método mutável. Ele não altera o comprimento de this, mas mudará o conteúdo de this e criará novas propriedades ou excluirá propriedades existentes, se necessário.

O método copyWithin() preserva slots vazios. Se a região a ser copiada for sparse, os novos índices correspondentes dos slots vazios são excluídos e também se tornam slots vazios.

O método copyWithin() é genérico. Ele apenas espera que o valor de this tenha uma propriedade length 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étodo copyWithin() lê a propriedade length do this 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.