Array : mthode values()

Baseline Large disponibilit

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.

En savoir plus
Voir la compatibilit complte

La mthode values() des instances de Array retourne un nouvel objet itrateur de tableau qui itre sur la valeur de chaque lment du tableau.

Exemple interactif

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

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

// Rsultat attendu : "a"
// Rsultat attendu : "b"
// Rsultat attendu : "c"

Syntaxe

values()

Description

Array.prototype.values() est l'implmentation par dfaut de Array.prototype[Symbol.iterator]().

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

Lorsqu'elle est utilise sur un tableau creux, la mthode values() itre sur les cases vides comme si elles avaient la valeur non dfinie (undefined).

La mthode values() est gnrique. Elle attend seulement que la valeur de this possde une proprit length et des proprits indices entiers.

Exemples

Itrer avec une boucle `for...of`

Comme values() retourne un itrateur itrable, vous pouvez utiliser une boucle for...of pour l'itrer.

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

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

Itrer avec `next()`

Comme la valeur de retour est aussi un itrateur, vous pouvez appeler directement sa mthode 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

Rutilisation de l'itrable

Attention : L'objet itrateur de tableau doit tre utilis une seule fois. Ne le rutilisez pas.

L'itrable retourn par values() n'est pas rutilisable. Lorsque next().done = true ou que currentIndex > length, la boucle for...of se termine et toute itration supplmentaire 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);
}
// Pas de sortie

Si vous utilisez une instruction break pour arrter l'itration prmaturment, l'itrateur peut reprendre la position courante lors de la prochaine itration.

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"

Aucune valeur n'est stocke dans l'objet itrateur de tableau retourn par values() : il stocke l'adresse du tableau utilis lors de sa cration et lit l'indice courant chaque itration. Ainsi, la valeur retourne dpend de la valeur stocke cet indice au moment de l'itration. Si les valeurs du tableau changent, celles de l'itrateur 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 mthodes itratives, l'itrateur de tableau ne mmorise pas la longueur du tableau sa cration, mais la lit chaque itration. Ainsi, si le tableau grandit pendant l'itration, l'itrateur visite aussi les nouveaux lments. Cela peut entraner des boucles infinies.

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

Itration sur les tableaux creux

values() visite les cases vides comme si elles valent undefined.

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

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

La mthode values() lit la proprit length de this puis accde chaque proprit dont la cl est un entier non ngatif infrieur 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