Les protocoles d'itération

Un des ajouts à ECMAScript 2015 (ES6) n'est ni une nouvelle syntaxe ni un nouvel objet natif mais des protocoles. Ces protocoles peuvent être implémentés par n'importe quel objet qui respecte certaines conventions.

Il existe deux protocoles concernant l'itération : le protocole « itérable » et le protocole « itérateur ».

Le protocole « itérable »

Le protocole « itérable » permet aux objets JavaScript de définir ou de personnaliser leur comportement lors d'une itération, par exemple la façon dont les valeurs seront parcourues avec une boucle for..of. Certains types natifs tels que Array ou Map possèdent un comportement itératif par défaut, d'autres types, comme Object n'ont pas ce type de comportement.

Afin d'être itérable, un objet doit implémenter la méthode @@iterator, cela signifie que l'objet (ou un des objets de sa chaîne de prototypes) doit avoir une propriété avec une clé @@iterator qui est accessible via Symbol.iterator :

Propriété Valeur
[Symbol.iterator] Une fonction sans argument qui renvoie un objet conforme au protocole itérateur.

Lorsqu'on doit itérer sur un objet (ex. : au début d'une boucle for..of), sa méthode @@iterator est appelée sans argument et l'itérateur qui est renvoyé est utilisé afin d'obtenir les valeurs sur lesquelles itérer.

Le protocole « itérateur »

Le protocole « itérateur » définit une façon standard pour produire une suite de valeurs (finie ou infinie).

Un objet est considéré comme un itérateur lorsqu'il implémente une méthode next() avec la sémantique suivante :

Propriété Valeur
next

Une fonction sans argument qui renvoie un objet qui possède deux propriétés :

  • done (un booléen)
    • Qui vaut true lorsque l'itérateur a fini la suite. Dans ce cas, la propriété value sera facultative et permettra de spécifier la valeur de retour de l'itérateur. Les valeurs de retour sont détaillées ici.
    • Qui vaut false lorsque l'itérateur a pu produire la prochaine valeur de la suite. Si on ne définit pas la propriété done, on aura ce comportement par défaut.
  • value : n'importe quelle valeur JavaScript, renvoyée par l'itérateur. Cette propriété peut être absente lorsque done vaut true.

La méthode next doit toujours renvoyer un objet contenant les propriétés done et value. Si c'est une valeur primitive qui est renvoyée (ex. false ou undefined), une exception TypeError sera levée ("iterator.next() returned a non-object value").

Certains itérateurs sont des itérables :

var unTableau = [1, 5, 7];
var élémentsDuTableau = unTableau.entries();

élémentsDuTableau.toString();    // "[object Array Iterator]"
élémentsDuTableau === élémentsDuTableau[Symbol.iterator]();    // true

Exemples d'utilisation des protocoles d'itération

Une String est un exemple d'objet natif itérable :

var uneChaîne = "coucou";
typeof uneChaîne[Symbol.iterator];           // "function"

L'itérateur par défaut d'un objet String renverra les caractères de la chaîne les uns à la suite des autres :

var itérateur = uneChaîne[Symbol.iterator]();
itérateur + "";     // "[object String Iterator]"

itérateur.next();  // { value: "c", done: false }
itérateur.next();  // { value: "o", done: false }
itérateur.next();  // { value: "u", done: false }
itérateur.next();  // { value: "c", done: false }
itérateur.next();  // { value: "o", done: false }
itérateur.next();  // { value: "u", done: false }
itérateur.next();  // { value: undefined, done: true }

Certains éléments natifs du langage, tels que l'opérateur de décomposition, utilisent ce même protocole :

[...uneChaîne];   // ["c", "o", "u", "c", "o", "u"]

Il est possible de redéfinir le comportement par défaut en définissant soi-même le symbole @@iterator :

var uneChaîne = new String("yo");          // on construit un objet String explicitement afin d'éviter la conversion automatique

uneChaîne[Symbol.iterator] = function() {
  return { // l'objet itérateur qui renvoie un seul élément, la chaîne "bop"
    next: function() {
      if (this._first) {
        this._first = false;
        return { value: "bop", done: false };
      } else {
        return { done: true };
      }
    },
    _first: true
  };
};

On notera que redéfinir le symbole @@iterator affecte également le comportement des éléments du langage qui utilisent le protocole :

[...uneChaîne];  // ["bop"]
uneChaîne + "";  // "yo"

Exemples d'itérables

Les itérables natifs

String, Array, TypedArray, Map et Set sont des itérables natifs car leurs prototypes possèdent une méthode @@iterator.

Les itérables définis par l'utilisateur

Il est possible de construire un itérable dans un script de la façon suivante :

var monItérable = {};
monItérable[Symbol.iterator] = function* () {
    yield 1;
    yield 2;
    yield 3;
};
[...monItérable]; // [1, 2, 3]

Les API natives utilisant des itérables

Plusieurs API utilisent les itérables, par exemple : Map([itérable]), WeakMap([itérable]), Set([itérable]) et WeakSet([itérable]) :

var monObjet = {};
new Map([[1,"a"],[2,"b"],[3,"c"]]).get(2);  // "b"
new WeakMap([[{},"a"],[monObjet,"b"],[{},"c"]]).get(monObjet); // "b"
new Set([1, 2, 3]).has(3);    // true
new Set("123").has("2");      // true
new WeakSet(function*() {
    yield {};
    yield monObjet;
    yield {};
}()).has(monObjet);           // true

ainsi que Promise.all(itérable), Promise.race(itérable), Array.from()

Les éléments de syntaxe utilisant des itérables

Certains éléments du langage utilisent des itérables, par exemple : for..of, l'opérateur de décomposition, yield*, l'affectation par décomposition :

for(let value of ["a", "b", "c"]){
    console.log(value);
}
// "a"
// "b"
// "c"

[..."abc"]; // ["a", "b", "c"]

function* gen(){
  yield* ["a", "b", "c"];
}

gen().next(); // { value:"a", done:false }

[a, b, c] = new Set(["a", "b", "c"]);
a; // "a"

Itérables mal-formés

Si une méthode @@iterator d'un objet itérable ne renvoie pas d'objet itérateur, on dira que cet objet est un itérable mal-formé. Utiliser de tels itérables peut provoquer des exceptions lors de l'exécution ou un comportement erratique :

var itérableMalFormé = {}
itérableMalFormé[Symbol.iterator] = () => 1
[...itérableMalFormé] // TypeError: [] is not a function

Exemples d'itérateurs

Un itérateur simple

function créerItérateur(tableau){
    var nextIndex = 0;
    
    return {
       next: function(){
           return nextIndex < tableau.length ?
               {value: tableau[nextIndex++], done: false} :
               {done: true};
       }
    }
}

var it = créerItérateur(['yo', 'ya']);

console.log(it.next().value); // 'yo'
console.log(it.next().value); // 'ya'
console.log(it.next().done);  // true

Un itérateur infini

function créateurID(){
    var index = 0;
    
    return {
       next: function(){
           return {value: index++, done: false};
       }
    }
}

var it = créateurID();

console.log(it.next().value); // '0'
console.log(it.next().value); // '1'
console.log(it.next().value); // '2'
// ...

Avec un générateur

function* créerUnGénérateurSimple(tableau){
    var nextIndex = 0;
    
    while(nextIndex < tableau.length){
        yield tableau[nextIndex++];
    }
}

var gen = créerUnGénérateurSimple(['yo', 'ya']);

console.log(gen.next().value); // 'yo'
console.log(gen.next().value); // 'ya'
console.log(gen.next().done);  // true

function* créateurID(){
    var index = 0;
    while(true)
        yield index++;
}

var gen = créateurID();

console.log(gen.next().value); // '0'
console.log(gen.next().value); // '1'
console.log(gen.next().value); // '2'

Un générateur est-il un itérateur ou un itérable ?

Les deux réponses sont correctes :

var unObjetGénérateur = function*(){
    yield 1;
    yield 2;
    yield 3;
}()
typeof unObjetGénérateur.next                
// "function", car il possède une fonction next, c'est donc un itérateur
typeof unObjetGénérateur[Symbol.iterator]    
// "function", car il possède une méthode @@iterator, c'est donc un itérable
unObjetGénérateur[Symbol.iterator]() === unObjetGénérateur  
// vrai car la méthode @@iterator renvoie elle-même, un itérateur, c'est donc un itérable bien formé
[...unObjetGénérateur]                       
// [1, 2, 3]

Compatibilité des navigateurs

Fonctionnalité Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Support simple 39.0 27.0 (27.0) Pas de support 26 Pas de support
IteratorResult plutôt qu'une exception (Oui) 29.0 (29.0) Pas de support (Oui) Pas de support
Fonctionnalité Android Webview Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile Chrome pour Android
Support simple Pas de support (Oui) 27.0 (27.0) Pas de support Pas de support Pas de support 39.0
IteratorResult plutôt qu'une exception Pas de support ? 29.0 (29.0) Pas de support Pas de support Pas de support (Oui)

Notes spécifiques à Firefox

Renvoi d'un objet IteratorResult à la place d'une exception

À partir de Gecko 29 (Firefox 29 / Thunderbird 29 / SeaMonkey 2.26), un générateur qui a fini ne lève plus d'exception TypeError. À la place, il renvoie un objet IteratorResult de la forme { value: undefined, done: true } (bug 958951).

La propriété Iterator et le symbole @@iterator

À partir de Gecko 17 (Firefox 17 / Thunderbird 17 / SeaMonkey 2.14) et jusqu'à Gecko 26 (Firefox 26 / Thunderbird 26 / SeaMonkey 2.23 / Firefox OS 1.2) la propriété iterator était utilisée (bug 907077), de Gecko 27 à Gecko 35 la propriété de substitution "@@iterator" a été utilisée. Depuis Gecko 36 (Firefox 36 / Thunderbird 36 / SeaMonkey 2.33), le symbole @@iterator a été implémenté (bug 918828).

Spécifications

Spécification État Commentaires
ECMAScript 2015 (6th Edition, ECMA-262)
La définition de 'Iteration' dans cette spécification.
Standard Définition initiale
ECMAScript 2017 Draft (ECMA-262)
La définition de 'Iteration' dans cette spécification.
Projet  

Voir aussi

  • Pour plus d'informations sur les générateurs définis par ES6, voir la page dédiée.

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : SphinxKnight, syntaxucre, Goofy, Nfroidure, teoli
 Dernière mise à jour par : SphinxKnight,