O método copyWithin() copia parte de um array para outra localização no mesmo array e o retorna sem alterar seu tamanho.
O método copyWithin() copia parte de um array para outra localização no mesmo array e o retorna sem alterar seu tamanho.
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"]
copyWithin(target)
copyWithin(target, start)
copyWithin(target, start, end)
targetÍndice de base zero à qual copiar a sequência para, convertido para inteiro.
target < 0, target + array.length é utilizado.target < -array.length, 0 é utilizado.target >= array.length, nada é copiado.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.
start < 0, start + array.length é utilizado.start < -array.length ou start é omitido, 0 é utilizado.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.
end < 0, end + array.length é utilizado.end < -array.length, 0 é utilizado.end >= array.length ou end é omitido, array.length é utilizado, fazendo com que todos os elementos até o final sejam copiados.end é posicionado antes ou em start após a normalização, nada será copiado.O array modificado.
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.
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]
copyWithin() propagará slots vazios(empty).
console.log([1, , 3].copyWithin(2, 1, 2)); / [1, empty, empty]
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.
| Specification |
|---|
| ECMAScript® 2026 Language Specification # sec-array.prototype.copywithin |