Array : méthode values()

Baseline Widely available

Cette fonctionnalité est bien établie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis ⁨mai 2018⁩.

La méthode values() des instances de Array retourne un nouvel objet itérateur de tableau qui itère sur la valeur de chaque élément du tableau.

Exemple interactif

const array = ["a", "b", "c"];
const iterator = array.values();

for (const value of iterator) {
  console.log(value);
}

// Résultat attendu : "a"
// Résultat attendu : "b"
// Résultat attendu : "c"

Syntaxe

values()

Description

Array.prototype.values() est l'implémentation par défaut de Array.prototype[Symbol.iterator]().

Array.prototype.values === Array.prototype[Symbol.iterator]; // true

Lorsqu'elle est utilisée sur un tableau creux, la méthode values() itère sur les cases vides comme si elles avaient la valeur indéfinie (undefined).

La méthode values() est générique. Elle attend seulement que la valeur de this possède une propriété length et des propriétés à indices entiers.

Exemples

Itérer avec une boucle `for...of`

Comme values() retourne un itérateur itérable, vous pouvez utiliser une boucle for...of pour l'itérer.

const arr = ["a", "b", "c", "d", "e"];
const iterator = arr.values();

for (const letter of iterator) {
  console.log(letter);
} // "a" "b" "c" "d" "e"

Itérer avec `next()`

Comme la valeur de retour est aussi un itérateur, vous pouvez appeler directement sa méthode next().

const arr = ["a", "b", "c", "d", "e"];
const iterator = arr.values();
iterator.next(); // { value: "a", done: false }
iterator.next(); // { value: "b", done: false }
iterator.next(); // { value: "c", done: false }
iterator.next(); // { value: "d", done: false }
iterator.next(); // { value: "e", done: false }
iterator.next(); // { value: undefined, done: true }
console.log(iterator.next().value); // undefined

Réutilisation de l'itérable

Attention : L'objet itérateur de tableau doit être utilisé une seule fois. Ne le réutilisez pas.

L'itérable retourné par values() n'est pas réutilisable. Lorsque next().done = true ou que currentIndex > length, la boucle for...of se termine et toute itération supplémentaire n'a aucun effet.

const arr = ["a", "b", "c", "d", "e"];
const values = arr.values();
for (const letter of values) {
  console.log(letter);
}
// "a" "b" "c" "d" "e"
for (const letter of values) {
  console.log(letter);
}
// undefined

Si vous utilisez une instruction break pour arrêter l'itération prématurément, l'itérateur peut reprendre à la position courante lors de la prochaine itération.

const arr = ["a", "b", "c", "d", "e"];
const values = arr.values();
for (const letter of values) {
  console.log(letter);
  if (letter === "b") {
    break;
  }
}
// "a" "b"

for (const letter of values) {
  console.log(letter);
}
// "c" "d" "e"

Mutations pendant l'itération

Aucune valeur n'est stockée dans l'objet itérateur de tableau retourné par values() : il stocke l'adresse du tableau utilisé lors de sa création et lit l'indice courant à chaque itération. Ainsi, la valeur retournée dépend de la valeur stockée à cet indice au moment de l'itération. Si les valeurs du tableau changent, celles de l'itérateur changent aussi.

const arr = ["a", "b", "c", "d", "e"];
const iterator = arr.values();
console.log(iterator); // Array Iterator { }
console.log(iterator.next().value); // "a"
arr[1] = "n";
console.log(iterator.next().value); // "n"

Contrairement aux méthodes itératives, l'itérateur de tableau ne mémorise pas la longueur du tableau à sa création, mais la lit à chaque itération. Ainsi, si le tableau grandit pendant l'itération, l'itérateur visitera aussi les nouveaux éléments. Cela peut entraîner des boucles infinies.

const arr = [1, 2, 3];
for (const e of arr) {
  arr.push(e * 10);
}
// RangeError : longueur de tableau non valide

Itération sur les tableaux creux

values() visitera les cases vides comme si elles valaient undefined.

for (const element of [, "a"].values()) {
  console.log(element);
}
// undefined
// 'a'

Appeler `values()` sur des objets qui ne sont pas des tableaux

La méthode values() lit la propriété length de this puis accède à chaque propriété dont la clé est un entier non négatif inférieur à length.

const objetSimilaireTableau = {
  length: 3,
  0: "a",
  1: "b",
  2: "c",
  3: "d", // ignoré par values() car length vaut 3
};
for (const entry of Array.prototype.values.call(objetSimilaireTableau)) {
  console.log(entry);
}
// a
// b
// c