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éthodevalues() des instances deArray retourne un nouvel objetité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 deArray.prototype[Symbol.iterator]().

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

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

La méthodevalues() estgénérique. Elle attend seulement que la valeur dethis possède une propriétélength et des propriétés à indices entiers.

Exemples

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

Commevalues() retourne un itérateur itérable, vous pouvez utiliser une bouclefor...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éthodenext().

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é parvalues() n'est pas réutilisable. Lorsquenext().done = true ou quecurrentIndex > length,la bouclefor...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 instructionbreak 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"

Aucune valeur n'est stockée dans l'objet itérateur de tableau retourné parvalues() : 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 auxmé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 valaientundefined.

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

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

La méthodevalues() lit la propriétélength dethis 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