Iterator

Description

Voici tous les itérateurs JavaScript intégrés :

• L'itérateur de tableau retourné par Array.prototype.values(), Array.prototype.keys(), Array.prototype.entries(), Array.prototype[Symbol.iterator](), TypedArray.prototype.values(), TypedArray.prototype.keys(), TypedArray.prototype.entries(), TypedArray.prototype[Symbol.iterator]() et arguments[Symbol.iterator]().
• L'itérateur de chaîne de caractères retourné par String.prototype[Symbol.iterator]().
• L'itérateur de Map retourné par Map.prototype.values(), Map.prototype.keys(), Map.prototype.entries() et Map.prototype[Symbol.iterator]().
• L'itérateur de Set retourné par Set.prototype.values(), Set.prototype.keys(), Set.prototype.entries() et Set.prototype[Symbol.iterator]().
• L'itérateur de chaîne de caractères RegExp retourné par RegExp.prototype[Symbol.matchAll]() et String.prototype.matchAll().
• L'objet Generator retourné par les fonctions génératrices.
• L'itérateur de segments retourné par la méthode [Symbol.iterator]() de l'objet Segments retourné par Intl.Segmenter.prototype.segment().
• L'itérateur d'aide retourné par les méthodes d'aide d'itérateur telles que Iterator.prototype.filter() et Iterator.prototype.map().

Les API Web peuvent également retourner des itérateurs. Certaines réutilisent les itérateurs JavaScript principaux tandis que d'autres définissent leurs propres itérateurs. Par exemple :

• Les objets similaires à des tableaux tels que NodeList retournent un itérateur de tableau depuis leurs méthodes respectives keys(), values(), entries() et [Symbol.iterator]().
• Les objets similaires à des Map issus des API Web comme Headers retournent leur propre type d'itérateur, tel que itérateur de Headers, depuis leurs méthodes respectives keys(), values(), entries() et [Symbol.iterator]().
• Les objets similaires à des Set issus des API Web comme FontFaceSet retournent leur propre type d'itérateur, tel que itérateur de FontFaceSet, depuis leurs méthodes respectives keys(), values(), entries() et [Symbol.iterator]().

Chacun de ces itérateurs possède un objet prototype distinct, qui définit la méthode next() utilisée par l'itérateur en question. Par exemple, tous les objets itérateurs de chaîne de caractères héritent d'un objet caché StringIteratorPrototype, qui possède une méthode next() qui itère cette chaîne de caractères par points de code. StringIteratorPrototype possède également une propriété [Symbol.toStringTag] dont la valeur initiale est la chaîne de caractères "String Iterator". Cette propriété est utilisée dans Object.prototype.toString(). De même, d'autres prototypes d'itérateurs ont également leurs propres valeurs [Symbol.toStringTag], qui sont identiques aux noms donnés ci-dessus.

Tous ces objets prototype héritent de Iterator.prototype, qui fournit une méthode [Symbol.iterator]() qui retourne l'objet itérateur lui‑même, rendant l'itérateur également itérable.

Méthodes d'aide pour les itérateurs

La classe Iterator fournit elle-même certaines méthodes d'aide pour travailler avec les itérateurs. Par exemple, vous pourriez être tenté de faire ce qui suit :

const nomDuDepot = new Map([
  ["Anne", 1000],
  ["Bert", 1500],
  ["Carl", 2000],
]);

const depotTotal = [...nomDuDepot.values()].reduce((a, b) => a + b);

Cela convertit d'abord l'itérateur retourné par Map.prototype.values() en un tableau, puis utilise la méthode Array.prototype.reduce() pour calculer la somme. Cependant, cela crée un tableau intermédiaire et itère le tableau deux fois. À la place, vous pouvez utiliser la méthode reduce() de l'itérateur lui-même :

const depotTotal = nomDuDepot.values().reduce((a, b) => a + b);

Cette méthode peut être plus efficace, notamment en termes de mémoire, car elle n'itère l'itérateur qu'une seule fois, sans mémoriser aucune valeur intermédiaire. Les méthodes d'aide à l'itérateur sont nécessaires pour travailler avec des itérateurs infinis :

function* fibonacci() {
  let actuel = 1;
  let suivant = 1;
  while (true) {
    yield actuel;
    [actuel, suivant] = [suivant, actuel + suivant];
  }
}

const seq = fibonacci();
const troisPremiersChiffres = seq.find((n) => n >= 100);

Vous ne pouvez pas convertir seq en tableau, car il est infini. À la place, vous pouvez utiliser la méthode find() de l'itérateur lui-même, qui itère seq uniquement jusqu'à ce qu'il trouve la première valeur qui satisfait la condition.

Vous trouverez de nombreuses méthodes d'itérateur analogues aux méthodes de tableau, telles que :

Iterator.prototype.drop() et Iterator.prototype.take() combinés sont quelque peu analogues à Array.prototype.slice().

Objets d'aide à l'itérateur

Parmi les méthodes d'aide à l'itérateur, filter(), flatMap(), map(), drop(), et take() retournent un nouvel objet Aide à l'itérateur. L'aide à l'itérateur est également une instance de Iterator, ce qui rend ces méthodes d'aide chaînables. Tous les objets d'aide à l'itérateur héritent d'un objet prototype commun, qui implémente le protocole d'itérateur :

next()

Appelle la méthode next() de l'itérateur sous-jacent, applique la méthode d'aide au résultat et renvoie le résultat.

return()

Appelle la méthode return() de l'itérateur sous-jacent et retourne le résultat.

L'aide à l'itérateur partage la même source de données que l'itérateur sous-jacent, donc l'itération de l'aide à l'itérateur entraîne également l'itération de l'itérateur sous-jacent. Il n'existe aucun moyen de dupliquer un itérateur pour le parcourir plusieurs fois.

const it = [1, 2, 3].values();
const it2 = it.drop(0); // Essentiellement une copie
console.log(it.next().value); // 1
console.log(it2.next().value); // 2
console.log(it.next().value); // 3

Itérateurs appropriés

Il existe deux types « d'itérateurs » : les objets conformes au protocole itérateur (qui, au minimum, nécessite uniquement la présence d'une méthode next()) et les objets qui héritent de la classe Iterator, qui bénéficient des méthodes d'aide. Ils ne s'impliquent pas mutuellement — les objets qui héritent de Iterator ne deviennent pas automatiquement des itérateurs, car la classe Iterator ne définit pas de méthode next(). Au lieu de cela, l'objet doit définir lui-même une méthode next(). Un itérateur approprié est celui qui respecte à la fois le protocole itérateur et hérite de Iterator, et la plupart du code s'attend à ce que les itérateurs soient des itérateurs appropriés et que les objets itérables retournent des itérateurs appropriés. Pour créer des itérateurs appropriés, définissez une classe qui étend Iterator, ou utilisez la méthode Iterator.from().

class MonIterateur extends Iterator {
  next() {
    // …
  }
}

const monIterateur = Iterator.from({
  next() {
    // …
  },
});

Constructeur

Iterator()

Destiné à être étendu par d'autres classes qui créent des itérateurs. Lève une erreur lorsqu'il est construit seul.

Méthodes statiques

Iterator.concat()

Crée un nouvel objet Iterator à partir d'une liste d'objets itérables. Le nouvel itérateur produit les valeurs de chacun des itérables d'entrée, en séquence.

Iterator.from()

Crée un nouvel objet Iterator à partir d'un itérateur ou d'un objet itérable.

Iterator.zip() Expérimental

Crée un nouvel objet Iterator qui agrège les éléments de plusieurs objets itérables en produisant des tableaux contenant les éléments à la même position.

Iterator.zipKeyed() Expérimental

Crée un nouvel objet Iterator qui agrège les éléments de plusieurs objets itérables en produisant des objets contenant les éléments à la même position, avec des clés définies par l'entrée.

Propriétés d'instance

Ces propriétés sont définies sur Iterator.prototype et partagées par toutes les instances de Iterator.

Iterator.prototype.constructor

La fonction constructeur qui a créé l'objet instance. Pour les instances de Iterator, la valeur initiale est le constructeur Iterator.

Iterator.prototype[Symbol.toStringTag]

La valeur initiale de la propriété [Symbol.toStringTag] est la chaîne de caractères "Iterator". Cette propriété est utilisée dans Object.prototype.toString().

Note : Contrairement à la propriété [Symbol.toStringTag] de la plupart des classes intégrées, Iterator.prototype[Symbol.toStringTag] est modifiable pour des raisons de compatibilité web.

Méthodes d'instance

Iterator.prototype.drop()

Retourne un nouvel objet aide à l'itérateur qui ignore le nombre d'éléments donné au début de cet itérateur.

Iterator.prototype.every()

Retourne false si un élément ne satisfait pas la fonction de test fournie. Sinon, si l'itérateur est épuisé sans trouver un tel élément, retourne true.

Iterator.prototype.filter()

Retourne un nouvel objet aide à l'itérateur qui produit uniquement les éléments de l'itérateur pour lesquels la fonction de rappel fournie retourne true.

Iterator.prototype.find()

Retourne le premier élément produit par l'itérateur qui satisfait la fonction de test fournie. Si aucune valeur ne satisfait la fonction de test, undefined est retourné.

Iterator.prototype.flatMap()

Retourne un nouvel objet aide à l'itérateur qui prend chaque élément de l'itérateur d'origine, le passe dans une fonction de correspondance, et produit les éléments retournés par la fonction de correspondance (qui sont contenus dans un autre itérateur ou objet pouvant être parcouru).

Iterator.prototype.forEach()

Exécute une fonction fournie une fois pour chaque élément produit par l'itérateur.

Iterator.prototype.map()

Retourne un nouvel objet aide à l'itérateur qui produit les éléments de l'itérateur, chacun transformé par une fonction de correspondance.

Iterator.prototype.reduce()

Exécute une fonction de réduction fournie par l'utilisateur·ice sur chaque élément produit par l'itérateur, en passant la valeur retournée par le calcul sur l'élément précédent. Le résultat final de la réduction sur tous les éléments est une seule valeur.

Iterator.prototype.some()

Retourne true si un élément satisfait la fonction de test fournie. Sinon, si l'itérateur est épuisé sans trouver un tel élément, retourne false.

Iterator.prototype.take()

Retourne un nouvel objet aide à l'itérateur qui produit le nombre d'éléments donné dans cet itérateur puis se termine.

Iterator.prototype.toArray()

Crée une nouvelle instance de l'objet Array remplie avec les éléments produits par l'itérateur.

Iterator.prototype[Symbol.dispose]()

Appelle la méthode return() de this, si elle existe. Cela implémente le protocole de libération et permet de le libérer lorsqu'il est utilisé avec using ou await using.

Iterator.prototype[Symbol.iterator]()

Retourne l'objet itérateur lui-même. Cela permet aux objets itérateurs d'être également itérables.

Exemples

Utiliser un itérateur comme itérable

Tous les itérateurs intégrés sont également itérables, vous pouvez donc les utiliser dans une boucle for...of :

const tableauIterateur = [1, 2, 3].values();
for (const valeur of tableauIterateur) {
  console.log(valeur);
}
// Affiche : 1, 2, 3

Spécifications

Compatibilité des navigateurs

Voir aussi

• Prothèse d'émulation de Iterator dans core-js ^(angl.)
• Prothèse d'émulation es-shims de Iterator et des aides associées ^(angl.)
• L'instruction function*
• Protocoles d'itération