Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Array.prototype.with: cópia com um índice substituído

with devolve uma cópia superficial densa com um valor substituído no índice positivo ou negativo indicado.

Versão: ECMAScript 2023; example target: Node.js 24.22.2

Sintaxe

array.with(index, value)

array.with(index, value) cria um novo Array normal do mesmo comprimento, escreve value na posição escolhida e copia os restantes valores. Não altera array, ignora Symbol.species e os objetos não alterados mantêm as mesmas referências.

index é convertido em inteiro; um valor negativo conta desde o fim, logo -1 seleciona a última posição. Um índice menor que o negativo do comprimento ou maior ou igual ao comprimento lança RangeError. Os espaços vazios são lidos como undefined e materializados, tornando o resultado denso.

O método é genérico para array-like e foi normalizado no ECMAScript 2023. Um recetor null ou undefined lança TypeError; propagam-se erros de conversão do comprimento ou índice, getters e traps de proxy, e um comprimento excessivo também pode produzir RangeError.

Exemplos

const source = [{ id: "a" }, { id: "b" }, { id: "c" }];
const changed = source.with(-2, { id: "B" });
console.log(changed.map(item => item.id).join(","));
console.log(source.map(item => item.id).join(","));
console.log(changed !== source, changed[0] === source[0]);

const dense = [, 2].with(1, 9);
console.log(dense.length, 0 in dense, dense[0] === undefined, dense[1]);
try { [1].with(2, 0); } catch (error) { console.log(error instanceof RangeError); }

Resultado

a,B,c
a,b,c
true true
2 true true 9
true

Fontes