Array.prototype.copyWithin() - JavaScript | MDN

Toggle sidebar

Theme

OS default
Light
Dark

Português (do Brasil)

Remember language Learn more

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

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.

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

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.

Help improve MDN

Was this page helpful to you?

Yes No

Learn how to contribute

This page was last modified on 17 de fev. de 2025 by MDN contributors.

View this page on GitHub • Report a problem with this content

Array.prototype.copyWithin()

In this article

Experimente

Sintaxe

Parâmetros

Valor de retorno

Descrição

Exemplos

Usando copyWithin()

Usando copyWithin() em arrays sparse

Chamando copyWithin() em objetos não array

Especificações

Compatibilidade com navegadores

Veja também

Help improve MDN