CKTIS / JavaScript
`length`: a propriedade modificável de um array
Lê `arr.length` para obter o comprimento do array ou atribui-lhe um valor para encurtar o mesmo array ou aumentá-lo sem criar elementos.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
arr.length
arr.length = newLengtharr.length é uma propriedade de dados própria de uma instância de Array, não a propriedade length do construtor Array. Inicialmente permite escrita, mas não é enumerável nem configurável. O seu valor é superior a qualquer índice próprio do array e pode exceder o número de elementos presentes.
Reduzir length elimina os elementos próprios cujo índice seja igual ou superior ao novo comprimento. arr.length = 0 esvazia um array normal sem o substituir: a alteração é visível através de todas as referências ao mesmo array. Aumentar o comprimento deixa posições vazias, não elementos com o valor undefined, e não recupera os elementos eliminados. Criar um elemento num índice válido i igual ou superior ao comprimento atual aumenta-o para i + 1.
O comprimento é um inteiro do tipo Number entre 0 e 2 ** 32 - 1, inclusive. Quando length permite escrita, o valor atribuído é convertido: por exemplo, "3" é aceite como 3, mas 2.5, -1 e 2 ** 32 provocam um RangeError. Converter um Symbol ou um BigInt provoca antes um TypeError.
Se, ao encurtar o array, for encontrado um elemento não configurável, a operação para nesse índice. O comprimento passa a ser esse índice mais um, e os elementos de índice superior já eliminados não são repostos. Também é possível impedir permanentemente a escrita em length com writable: false. Isto bloqueia atribuições a length e a adição de elementos que aumentariam o comprimento, mas não impede todas as alterações aos elementos. Em ambos os casos, uma atribuição falhada provoca um TypeError em modo estrito; fora desse modo, não lança uma exceção.
Exemplos
(() => {
"use strict";
const arr = ["a", "b", "c"];
const alias = arr;
arr.length = 1;
console.log(`${alias.length}: ${alias.join(",")}`);
arr.length = 3;
arr[2] = undefined;
console.log(`${arr.length}: ${Object.hasOwn(arr, 1)}, ${Object.hasOwn(arr, 2)}`);
arr[4] = "e";
console.log(`${arr.length}: ${arr[4]}`);
try {
arr.length = 2.5;
} catch (error) {
console.log(`${error.name}: ${arr.length}`);
}
})();Resultado
1: a 3: false, true 5: e RangeError: 5
`alias` permite observar o encurtamento do mesmo array. Depois de aumentar o comprimento, `Object.hasOwn` distingue a posição vazia no índice `1` do valor `undefined` atribuído explicitamente ao índice `2`. Escrever no índice `4` aumenta o comprimento para `5`; a rejeição de `2.5` não o altera.
Lições relacionadas
- JavaScript · Lição 20 · Avançado · Versão: 4