From bf8e099b9c8b3c60d60b3712b4fc97b052c39887 Mon Sep 17 00:00:00 2001 From: julieng Date: Tue, 3 Aug 2021 08:03:23 +0200 Subject: convert content to md --- .../reference/iteration_protocols/index.md | 281 +++++++++++---------- 1 file changed, 147 insertions(+), 134 deletions(-) (limited to 'files/fr/web/javascript/reference/iteration_protocols') diff --git a/files/fr/web/javascript/reference/iteration_protocols/index.md b/files/fr/web/javascript/reference/iteration_protocols/index.md index 6e1b27bbae..a6e2b15f68 100644 --- a/files/fr/web/javascript/reference/iteration_protocols/index.md +++ b/files/fr/web/javascript/reference/iteration_protocols/index.md @@ -10,89 +10,106 @@ tags: translation_of: Web/JavaScript/Reference/Iteration_protocols original_slug: Web/JavaScript/Reference/Les_protocoles_iteration --- -
{{jsSidebar("More")}}
+{{jsSidebar("More")}} -

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.

+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 ».

+Il existe deux protocoles concernant l'itération : [le protocole « itérable »](#itérable) et [le protocole « itérateur »](#itérateur). -

Le protocole « itérable »

+## 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 {{jsxref("Instructions/for...of", "for..of")}}. Certains types natifs tels que {{jsxref("Array")}} ou {{jsxref("Map")}} possèdent un comportement itératif par défaut, d'autres types, comme {{jsxref("Object")}} n'ont pas ce type de comportement.

+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 {{jsxref("Instructions/for...of", "for..of")}}. Certains types natifs tels que {{jsxref("Array")}} ou {{jsxref("Map")}} possèdent un comportement itératif par défaut, d'autres types, comme {{jsxref("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 {{jsxref("Symbol.iterator")}} :

+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](/fr/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain)) doit avoir une propriété avec une clé **`@@iterator`** qui est accessible via {{jsxref("Symbol.iterator")}} : - - - - - - - - - - - - - -
PropriétéValeur
[Symbol.iterator]Une fonction sans argument qui renvoie un objet conforme au protocole itérateur.
+| Propriété | Valeur | +| ------------------- | ---------------------------------------------------------------------------------------------- | +| `[Symbol.iterator]` | Une fonction sans argument qui renvoie un objet conforme au [protocole itérateur](#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.

+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 » -

Le protocole « itérateur » définit une façon standard pour produire une suite de valeurs (finie ou infinie) ainsi qu'une valeur de retour lorsque toutes les valeurs ont été générées.

+Le protocole « **itérateur** » définit une façon standard pour produire une suite de valeurs (finie ou infinie) ainsi qu'une valeur de retour lorsque toutes les valeurs ont été générées. -

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

+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 au moins 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 {{jsxref("TypeError")}} sera levée ("iterator.next() returned a non-object value").

-
PropriétéValeur
next +

+ Une fonction sans argument qui renvoie un objet qui possède au moins + 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 + {{jsxref("TypeError")}} sera levée ("iterator.next() returned + a non-object value"). +

+
-

Certains itérateurs sont des itérables :

+Certains itérateurs sont des itérables : -
var unTableau = [1, 5, 7];
+```js
+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

+## Exemples d'utilisation des protocoles d'itération -

Une {{jsxref("String")}} est un exemple d'objet natif itérable :

+Une {{jsxref("String")}} est un exemple d'objet natif itérable : -
var uneChaîne = "coucou";
+```js
+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 :

+[L'itérateur par défaut d'un objet `String`](/fr/docs/Web/JavaScript/Reference/Objets_globaux/String/@@iterator) renverra les caractères de la chaîne les uns à la suite des autres : -
var itérateur = uneChaîne[Symbol.iterator]();
+```js
+var itérateur = uneChaîne[Symbol.iterator]();
 itérateur + "";     // "[object String Iterator]"
 
 itérateur.next();  // { value: "c", done: false }
@@ -101,15 +118,19 @@ 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 }
+itérateur.next(); // { value: undefined, done: true } +``` -

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

+Certains éléments natifs du langage, tels que [la syntaxe de décomposition](/fr/docs/Web/JavaScript/Reference/Opérateurs/Opérateur_de_décomposition), utilisent ce même protocole : -
[...uneChaîne];   // ["c", "o", "u", "c", "o", "u"]
+```js +[...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 :

+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
+```js
+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"
@@ -124,38 +145,41 @@ uneChaîne[Symbol.iterator] = function() {
     _first: true
   };
 };
-
+``` -

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

+On notera que redéfinir le symbole `@@iterator` affecte également le comportement des éléments du langage qui utilisent le protocole : -
[...uneChaîne];  // ["bop"]
+```js
+[...uneChaîne];  // ["bop"]
 uneChaîne + "";  // "yo"
-
+``` -

Exemples d'itérables

+## Exemples d'itérables -

Les itérables natifs

+### Les itérables natifs -

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

+{{jsxref("String")}}, {{jsxref("Array")}}, {{jsxref("TypedArray")}}, {{jsxref("Map")}} et {{jsxref("Set")}} sont des itérables natifs car leurs prototypes possèdent une méthode `@@iterator`. -

Les itérables définis par l'utilisateur

+### Les itérables définis par l'utilisateur -

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

+Il est possible de construire un itérable dans un script de la façon suivante : -
var monItérable = {};
+```js
+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

+### Les API natives utilisant des itérables -

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

+Plusieurs API utilisent les itérables, par exemple : {{jsxref("Map", "Map([itérable])")}}, {{jsxref("WeakMap", "WeakMap([itérable])")}}, {{jsxref("Set", "Set([itérable])")}} et {{jsxref("WeakSet", "WeakSet([itérable])")}} : -
var monObjet = {};
+```js
+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
@@ -165,15 +189,16 @@ new WeakSet(function*() {
     yield monObjet;
     yield {};
 }()).has(monObjet);           // true
-
+``` -

ainsi que {{jsxref("Promise.all", "Promise.all(itérable)")}}, {{jsxref("Promise.race", "Promise.race(itérable)")}}, {{jsxref("Array.from", "Array.from()")}}

+ainsi que {{jsxref("Promise.all", "Promise.all(itérable)")}}, {{jsxref("Promise.race", "Promise.race(itérable)")}}, {{jsxref("Array.from", "Array.from()")}} -

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

+### Les éléments de syntaxe utilisant des itérables -

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

+Certains éléments du langage utilisent des itérables, par exemple : [`for..of`](/fr/docs/Web/JavaScript/Reference/Instructions/for...of), [la syntaxe de décomposition](/fr/docs/Web/JavaScript/Reference/Op%C3%A9rateurs/Op%C3%A9rateur_de_d%C3%A9composition), [yield\*](/fr/docs/Web/JavaScript/Reference/Op%C3%A9rateurs/yield*), [l'affectation par décomposition](/fr/docs/Web/JavaScript/Reference/Op%C3%A9rateurs/Affecter_par_d%C3%A9composition) : -
for(let value of ["a", "b", "c"]){
+```js
+for(let value of ["a", "b", "c"]){
     console.log(value);
 }
 // "a"
@@ -190,28 +215,29 @@ gen().next(); // { value:"a", done:false }
 
 [a, b, c] = new Set(["a", "b", "c"]);
 a; // "a"
+```
 
-
- -

Itérables mal-formés

+### 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 :

+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
+```js
+var itérableMalFormé = {}
+itérableMalFormé[Symbol.iterator] = () => 1
 [...itérableMalFormé] // TypeError: [] is not a function
-
+``` -

Exemples d'itérateurs

+## Exemples d'itérateurs -

Un itérateur simple

+### Un itérateur simple -
function créerItérateur(tableau){
+```js
+function créerItérateur(tableau){
     var nextIndex = 0;
 
     return {
        next: function(){
-           return nextIndex < tableau.length ?
+           return nextIndex < tableau.length ?
                {value: tableau[nextIndex++], done: false} :
                {done: true};
        }
@@ -223,11 +249,12 @@ 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

+### Un itérateur infini -
function créateurID(){
+```js
+function créateurID(){
     var index = 0;
 
     return {
@@ -243,14 +270,15 @@ console.log(it.next().value); // '0'
 console.log(it.next().value); // '1'
 console.log(it.next().value); // '2'
 // ...
-
+``` -

Avec un générateur

+### Avec un générateur -
function* créerUnGénérateurSimple(tableau){
+```js
+function* créerUnGénérateurSimple(tableau){
     var nextIndex = 0;
 
-    while(nextIndex < tableau.length){
+    while(nextIndex < tableau.length){
         yield tableau[nextIndex++];
     }
 }
@@ -272,11 +300,12 @@ var gen = créateurID();
 console.log(gen.next().value); // '0'
 console.log(gen.next().value); // '1'
 console.log(gen.next().value); // '2'
-
+``` -

Avec une classe ECMAScript 2015 (ES6)

+### Avec une classe ECMAScript 2015 (ES6) -
class ClasseSimple {
+```js
+class ClasseSimple {
   constructor(data) {
     this.index = 0;
     this.data = data;
@@ -284,8 +313,8 @@ console.log(gen.next().value); // '2'
 
   [Symbol.iterator]() {
     return {
-      next: () => {
-        if (this.index < this.data.length) {
+      next: () => {
+        if (this.index < this.data.length) {
           return {value: this.data[this.index++], done: false};
         } else {
           this.index = 0;
@@ -304,13 +333,14 @@ const simple = new ClasseSimple([1,2,3,4,5]);
 for (const val of simple) {
   console.log(val);  // '1' '2' '3' '4' '5'
 }
-
+``` -

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

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

Les deux réponses sont correctes :

+Les deux réponses sont correctes : -
var unObjetGénérateur = function*(){
+```js
+var unObjetGénérateur = function*(){
     yield 1;
     yield 2;
     yield 3;
@@ -323,32 +353,15 @@ 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]
-
+``` -

Spécifications

+## Spécifications - - - - - - - - - - - - - - - - - - -
SpécificationÉtatCommentaires
{{SpecName('ES2015', '#sec-iteration', 'Iteration')}}{{Spec2('ES2015')}}Définition initiale
{{SpecName('ESDraft', '#sec-iteration', 'Iteration')}}{{Spec2('ESDraft')}} 
+| Spécification | État | Commentaires | +| ------------------------------------------------------------------------ | ---------------------------- | ------------------- | +| {{SpecName('ES2015', '#sec-iteration', 'Iteration')}} | {{Spec2('ES2015')}} | Définition initiale | +| {{SpecName('ESDraft', '#sec-iteration', 'Iteration')}} | {{Spec2('ESDraft')}} |   | -

Voir aussi

+## Voir aussi - +- Pour plus d'informations sur les générateurs définis par ES2015, voir [la page dédiée](/fr/docs/Web/JavaScript/Reference/Instructions/function*). -- cgit v1.2.3-54-g00ecf