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 September 2016.

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

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

Valor de retorno

O array modificado.

Descrição

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()

js
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).

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

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

Especificações

Specification
ECMAScript® 2025 Language Specification
# sec-array.prototype.copywithin

Compatibilidade com navegadores

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
copyWithin

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support

Veja também