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
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ósstart
depois da normalização, a cópia só acontece até o final doarray.length
(em outras palavras,copyWithin()
nunca estende o array).
- Índice negativo será contado a partir do final do array — se
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
oustart
é omitido,0
é utilizado. - Se
start >= array.length
, nada é copiado.
- Índice negativo será contado a partir do final do array — se
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 oend
.- Í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
ouend
é omitido,array.length
é utilizado, fazendo com que todos os elementos até o final sejam copiados. - Se
end
é posicionado antes ou emstart
após a normalização, nada será copiado.
- Índice negativo será contado a partir do final do array — se
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()
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.
Especificações
Specification |
---|
ECMAScript Language Specification # sec-array.prototype.copywithin |
Compatibilidade com navegadores
BCD tables only load in the browser