Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

Protocole d’itération : next(), return(), value et done

Testez `done` plutôt que `value` pour détecter la fin du parcours. Voyez comment lire la valeur finale et quand `for...of` appelle la méthode facultative `return()`.

Version : ECMAScript 2024 and the current web platform; runtime support varies

Syntaxe

const iterator = iterable[Symbol.iterator]();
const result = iterator.next();
// result.done: completion flag; result.value: element or completion value
// When stopping early during manual iteration, call the optional method if callable:
if (typeof iterator.return === "function") {
  iterator.return();
}

Un itérateur synchrone est un objet dont la méthode next() renvoie un objet résultat (IteratorResult). Un objet itérable possède une méthode [Symbol.iterator]() qui renvoie un itérateur. La seule présence de next() ne rend pas un objet itérable ; un objet générateur joue les deux rôles. for...of obtient l’itérateur et appelle next() sans argument. Le sens d’un éventuel argument dépend de l’implémentation de l’itérateur.

Avec done: false, value est un élément, même s’il vaut undefined. Avec done: true, le parcours est terminé et value peut contenir une valeur finale que for...of ne transmet pas au corps de la boucle. L’absence de done équivaut à false ; for...of convertit cette propriété en booléen pour la tester. Une fois l’itérateur épuisé, les appels suivants à next() devraient encore indiquer done: true, mais le langage ne l’impose pas.

La méthode facultative return(value) signale que l’appelant arrête le parcours et donne à l’itérateur l’occasion de libérer ses ressources. En général, son résultat contient done: true et l’argument dans value. Un générateur peut toutefois renvoyer done: false s’il exécute un yield dans finally. En cas de sortie anticipée par break ou par une exception dans le corps de la boucle, for...of appelle return() sans argument si cette méthode existe et ignore les propriétés done et value du résultat. Il ne l’appelle ni à la fin normale du parcours ni si next() lève lui-même une exception.

Les appels manuels à next() ne ferment pas automatiquement l’itérateur : en cas d’arrêt anticipé, appelez vous-même return() si la méthode est appelable. for...of lève une TypeError si next() ou l’appel de return() lors de la fermeture ne renvoie pas un objet. Si la fermeture a été déclenchée par une exception du corps de la boucle, cette exception initiale est prioritaire.

Exemples

{
  function* sequence() {
    try {
      yield undefined;
      return "end";
    } finally {
      console.log("cleanup");
    }
  }

  function show(label, { done, value }) {
    console.log(`${label}: done=${done}, value=${value}`);
  }

  const full = sequence();
  show("next", full.next());
  show("next", full.next());
  show("next", full.next());

  for (const value of sequence()) {
    console.log(`loop: ${value}`);
    break;
  }

  const manual = sequence();
  manual.next();
  show("return", manual.return("stopped"));
}

Résultat

next: done=false, value=undefined
cleanup
next: done=true, value=end
next: done=true, value=undefined
loop: undefined
cleanup
cleanup
return: done=true, value=stopped

Trois générateurs distincts montrent la fin normale avec la valeur finale `end`, la fermeture automatique sur `break` et l’appel explicite à `return("stopped")`. Chaque générateur démarré affiche `cleanup` dans son bloc `finally`.

Leçons associées

  • JavaScript · Leçon 8 · Avancé · Version : 4

Sources