Array : propriété length

Exemple interactif

const clothing = ["chaussures", "chemises", "chaussettes", "pulls"];

console.log(clothing.length);
// Résultat attendu : 4

Valeur

Un entier positif inférieur à 2³².

Description

La valeur de la propriété length est un entier positif dont la valeur est inférieure à 2³².

const listeA = [1, 2, 3];
const listeB = new Array(6);

console.log(listeA.length);
// Résultat attendu : 3

console.log(listeB.length);
// Résultat attendu : 6

listeB.length = 2 ** 32; // 4294967296
// RangeError : Invalid array length

const listeC = new Array(-100); // Les nombres négatifs ne sont pas autorisés
// RangeError : Invalid array length

L'objet tableau observe la propriété length et synchronise automatiquement la valeur de length avec le contenu du tableau. Cela signifie :

• Définir la propriété length à une valeur inférieure à la longueur actuelle tronque le tableau — les éléments au-delà de la nouvelle valeur de length sont supprimés.
• Définir un indice de tableau (un entier positif inférieur à 2³²) au-delà de la valeur actuelle de length étend le tableau — la propriété length est augmentée pour refléter le nouvel indice le plus élevé.
• Définir la propriété length à une valeur invalide (par exemple, un nombre négatif ou un nombre non entier) lève une exception RangeError.

Lorsque la propriété length est définie à une valeur supérieure à la longueur actuelle, le tableau est étendu en ajoutant des emplacements vides, et non des valeurs undefined réelles. Les emplacements vides ont des interactions particulières avec les méthodes de tableau : voir méthodes de tableau et emplacements vides.

const tableau = [1, 2];
console.log(tableau);
// [ 1, 2 ]

tableau.length = 5; // On définit la longueur du tableau à 5 alors qu'elle vaut 2.
console.log(tableau);
// [ 1, 2, <3 éléments vides> ]

tableau.forEach((élément) => console.log(élément));
// 1
// 2

Voir aussi la relation entre longueur et propriétés numériques.

Exemples

Parcourir un tableau

Dans l'exemple suivant, on itère sur le tableau nombres en utilisant la propriété length afin de connaître son nombre d'éléments. La valeur de chaque élément est ensuite multipliée par deux :

const nombres = [1, 2, 3, 4, 5];
const longueur = nombres.length;
for (let i = 0; i < longueur; i++) {
  nombres[i] *= 2;
}
// nombres vaut maintenant [2, 4, 6, 8, 10]

Tronquer un tableau

L'exemple suivant raccourcit le tableau nombres à une longueur de 3 si sa longueur actuelle est supérieure à 3.

const nombres = [1, 2, 3, 4, 5];

if (nombres.length > 3) {
  nombres.length = 3;
}

console.log(nombres); // [1, 2, 3]
console.log(nombres.length); // 3
console.log(nombres[3]); // undefined ; les éléments supplémentaires sont supprimés

Créer un tableau vide de longueur fixe

Définir la propriété length à une valeur supérieure à la longueur actuelle crée un tableau creux.

const nombres = [];
nombres.length = 3;
console.log(nombres); // [vide x 3]

Tableau avec une propriété length non modifiable

La propriété length est automatiquement mise à jour par le tableau lorsque des éléments sont ajoutés au-delà de la longueur actuelle. Si la propriété length est rendue non modifiable, le tableau ne pourra pas la mettre à jour. Cela provoque une erreur en mode strict.

"use strict";

const nombres = [1, 2, 3, 4, 5];
Object.defineProperty(nombres, "length", { writable: false });
nombres[5] = 6; // TypeError : Cannot assign to read only property 'length' of object '[object Array]'
nombres.push(5); // TypeError : Cannot assign to read only property 'length' of object '[object Array]'

Spécifications

Compatibilité des navigateurs

Voir aussi

• Guide des collections indexées
• L'objet global Array
• La propriété TypedArray.prototype.length
• La propriété String.length
• RangeError : longueur de tableau invalide