recursal/MDN huggingface dataset:
Symbol.asyncIterator
====================

Le symbole connu **`Symbol.asyncIterator`** définit l'itérateur asynchrone par défaut d'un objet. Si cette propriété est définie sur un objet, celui-ci est un itérable asynchrone et peut être utilisé avec une boucle `for await...of`.

| Attributs de `Symbol.asyncIterator` |
| --- |
| Écrivable | Non |
| Énumérable | Non |
| Configurable | Non |

Description
-----------

Le symbole `Symbol.asyncIterator` est un symbole natif utilisé pour accéder à la méthode `@@asyncIterator` d'un objet. Pour qu'un objet soit un itérable asynchrone, il doit avoir une clé `Symbol.asyncIterator`.

Exemples
--------

### Itérable asynchrone personnalisé

Il est possible de définir son propre itérable en définissant la propriété `[Symbol.asyncIterator]` d'un objet :


```js
const myAsyncIterable = new Object();
myAsyncIterable[Symbol.asyncIterator] = async function\* () {
  yield "coucou";
  yield "l'itération";
  yield "asynchrone !";
};

(async () => {
  for await (const x of myAsyncIterable) {
    console.log(x);
    // expected output:
    // "coucou"
    // "l'itération"
    // "asynchrone !"
  }
})();
```

### Itérables asynchrones natifs

Il n'existe actuellement pas d'objets JavaScript natifs qui possèdent la clé `[Symbol.asyncIterator]` par défaut. Toutefois, les flux (*Streams*) WHATWG pourraient devenir les premiers objets natifs itérables asynchrones.

Spécifications
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.asynciterator |

Compatibilité des navigateurs
-----------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Voir aussi
----------

* Les protocoles d'itération
* `for await... of`
Constructeur Symbol()
=====================

Le constructeur `Symbol()` renvoie une valeur de type **`symbol`**. Ce n'est pas à proprement parler un constructeur, car il n'accepte pas la syntaxe `new Symbol()` et qu'il n'est pas prévu pour créer des sous-classes. On pourra l'utiliser comme valeur pour la clause `extends` d'une définition de classe, mais on ne pourra pas l'utiliser avec un appel `super`, cela entraînera une exception.

Exemple interactif
------------------

Syntaxe
-------


```js
Symbol();
Symbol(description);
```

### Paramètres

`description` Facultatif

Une chaîne de caractères qui décrit le symbole. Elle peut être utilisée pour le débogage mais ne permet pas d'accéder au symbole lui-même.

Exemples
--------

### Créer des symboles

Pour créer un nouveau symbole primitif, on écrit `Symbol()` en fournissant éventuellement une chaîne de caractères comme description :


```js
let sym1 = Symbol();
let sym2 = Symbol("toto");
let sym3 = Symbol("toto");
```


Dans le code précédent, on crée trois nouveaux symboles. On notera que `Symbol("toto")` ne convertit pas la chaîne de caractères `"toto"` en un symbole. C'est bien un nouveau symbole qui est créé chaque fois :


```js
Symbol("toto") === Symbol("toto"); // false
```

### `new Symbol(…)`

La syntaxe qui suit, utilisant l'opérateur `new`, déclenchera une exception `TypeError` :


```js
let sym = new Symbol(); // TypeError
```


Cela permet d'éviter aux développeuses et développeurs de créer un objet enveloppant une valeur symbole primitive plutôt qu'un nouveau symbole. Ce comportement se distingue des autres types de données primitifs pour lesquels c'est possible (par exemple `new Boolean()`, `new String()` et `new Number()`).

Si on souhaite vraiment envelopper un symbole dans une valeur objet, il faudra utiliser la fonction `Object()` :


```js
let sym = Symbol("toto");
let symObj = Object(sym);
typeof sym; // => "symbol"
typeof symObj; // => "object"
```

Spécifications
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol-constructor |

Compatibilité des navigateurs
-----------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Voir aussi
----------

* Prothèse d'émulation pour `Symbol` avec la bibliothèque d'émulation `core-js`
* La page du glossaire sur le type de données symbole
Symbol.isConcatSpreadable
=========================

Le symbole connu **`Symbol.isConcatSpreadable`** est utilisé pour configurer la façon dont un tableau est aplati lors d'une concaténation via la méthode `Array.prototype.concat()`.

Exemple interactif
------------------

Description
-----------

Le symbole `@@isConcatSpreadable` (`Symbol.isConcatSpreadable`) peut être défini comme une propriété propre ou héritée. C'est une valeur booléenne qui contrôle le comportement des tableaux et des objets semblables à des tableaux :

* Pour les tableaux, `concat` aplatira les tableaux par défaut. `Symbol.isConcatSpreadable` peut être utilisé pour obtenir le comportement opposé.
* Pour les objets semblables à des tableaux, par défaut, il n'y aucune mise à plat. `Symbol.isConcatSpreadable` permet de forcer cette mise à plat.

| Attributs de `Symbol.isConcatSpreadable` |
| --- |
| Écrivable | Non |
| Énumérable | Non |
| Configurable | Non |

Exemples
--------

### Tableaux (`Array`)

Par défaut, `Array.prototype.concat()` aplatit les tableaux pour le résultat de la concaténation :


```js
var alpha = ["a", "b", "c"],
  numérique = [1, 2, 3];

var alphaNumérique = alpha.concat(numérique);

console.log(alphaNumérique);
// Résultat : ['a', 'b', 'c', 1, 2, 3]
```


En définissant `Symbol.isConcatSpreadable` avec `false`, on peut désactiver le comportement par défaut :


```js
var alpha = ["a", "b", "c"],
  numérique = [1, 2, 3];

numérique[Symbol.isConcatSpreadable] = false;
var alphaNumérique = alpha.concat(numérique);

console.log(alphaNumérique);
// Résultat: ['a', 'b', 'c', [1, 2, 3] ]
```

### Objets semblables à des tableaux

Pour les objets semblables à un tableau, par défaut, il n'y a pas de fusion. Il faut donc que `Symbol.isConcatSpreadable` vaille `true` pour aplatir le tableau :


```js
var x = [1, 2, 3];

var fauxTableau = {
  [Symbol.isConcatSpreadable]: true,
  length: 2,
  0: "coucou",
  1: "monde",
};

x.concat(fauxTableau); // [1, 2, 3, "coucou", "monde"]
```


**Note :** La propriété `length` indique ici le nombre de propriétés à ajouter au tableau.

Spécifications
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.isconcatspreadable |

Compatibilité des navigateurs
-----------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Voir aussi
----------

* `Array.prototype.concat()`
Symbol.prototype.description
============================

La propriété en lecture seule **`description`** est une chaîne de caractères qui renvoie la description optionnelle de l'objet `Symbol`.

Exemple interactif
------------------

Syntaxe
-------


```js
Symbol("maDescription").description;
Symbol.iterator.description;
Symbol.for("toto").description;
```

Description
-----------

Les objets `Symbol` peuvent être créés avec une description facultative qui peut être utilisée pour du débogage mais sans accéder au symbole. La propriété `Symbol.prototype.description` peut être utilisée afin de lire cette description. Cette propriété est différente de `Symbol.prototype.toString()` car elle ne contient pas la chaîne de caractères "`Symbol()`" autour de la description (voir les exemples qui suivent).

Exemples
--------


```js
Symbol("desc").toString(); // "Symbol(desc)"
Symbol("desc").description; // "desc"
Symbol("").description; // ""
Symbol().description; // undefined

// symboles connus
Symbol.iterator.toString(); // "Symbol(Symbol.iterator)"
Symbol.iterator.description; // "Symbol.iterator"

// symboles globaux
Symbol.for("toto").toString(); // "Symbol(toto)"
Symbol.for("toto").description; // "toto"
```

Spécifications
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.prototype.description |

Compatibilité des navigateurs
-----------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Voir aussi
----------

* `Symbol.prototype.toString()`
* Prothèse d'émulation / *Polyfill* : https://npmjs.com/symbol.prototype.description
Symbol.prototype.toString()
===========================

La méthode **`toString()`** renvoie une chaîne de caractères représentant l'objet `Symbol`.

Exemple interactif
------------------

Syntaxe
-------


```js
Symbol().toString();
```

### Valeur de retour

Une chaîne de caractères qui représente l'objet `Symbol`.

Description
-----------

L'objet `Symbol` surcharge la méthode `toString()` d'`Object` et n'hérite pas de `Object.prototype.toString()`. Pour les objets `Symbol`, la méthode `toString()` renvoie représentation de l'objet sous forme d'une chaîne de caractères.

### Concaténation de chaînes et symboles

Bien qu'il soit possible d'appeler `toString()` pour les symboles, il n'est pas possible de concaténer une chaîne de caractères avec ce type d'objet :


```js
Symbol("toto") + "machin"; // TypeError : Impossible de convertir un symbole en chaîne de caractères
```

Exemples
--------


```js
Symbol("desc").toString(); // "Symbol(desc)"

// symboles connus
Symbol.iterator.toString(); // "Symbol(Symbol.iterator)

// symboles globaux
Symbol.for("toto").toString(); // "Symbol(toto)"
```

Spécifications
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.prototype.tostring |

Compatibilité des navigateurs
-----------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Voir aussi
----------

* `Object.prototype.toString()`
Symbol.keyFor()
===============

La méthode **`Symbol.keyFor(sym)`** permet de récupérer la clé d'un symbole donné qui est partagé via le registre global des symboles.

Exemple interactif
------------------

Syntaxe
-------


```js
Symbol.keyFor(sym);
```

### Paramètres

`sym`

Le symbole dont on souhaite connaître la clé. Ce paramètre est obligatoire.

### Valeur de retour

Une chaîne de caractères qui représente la clé d'un symbole donné si celui-ci est trouvé dans le registre global ou `undefined` sinon.

Exemples
--------


```js
var symboleGlobal = Symbol.for("toto"); // on crée un symbole global
Symbol.keyFor(symboleGlobal); // "toto"

var symboleLocal = Symbol();
Symbol.keyFor(symboleLocal); // undefined

// les symboles connus ne sont pas dans le registre
// global
Symbol.keyFor(Symbol.iterator); // undefined
```

Spécifications
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.keyfor |

Compatibilité des navigateurs
-----------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Voir aussi
----------

* `Symbol.for()`
Symbol.for()
============

La méthode **`Symbol.for(clé)`** permet de chercher parmi les symboles existants enregistrés dans le registre global de l'environnement d'exécution. Si un symbole associé à la clé donnée existe, il est renvoyé par la fonction, sinon un nouveau symbole associé à cette clé est créé dans le registre.

Exemple interactif
------------------

Syntaxe
-------


```js
Symbol.for(clé);
```

### Paramètres

clé

Une chaîne de caractères, obligatoire. La clé correspondant au symbole (également utilisée pour la description du symbole).

### Valeur de retour

Un symbole existant s'il en a été trouvé un avec la clé fournie. Sinon, un nouveau symbole est créé puis renvoyé par la méthode.

Description
-----------

À la différence de `Symbol()`, la méthode `Symbol.for()` crée un symbole enregistré dans le registre global. `Symbol.for()` ne crée pas nécessairement un nouveau symbole pour chaque appel, elle vérifie d'abord si un symbole avec la `clé` donnée est d'ores et déjà présent dans le registre. Si c'est le cas, le symbole correspondant est renvoyé, sinon `Symbol.for()` crée un nouveau symbol global.

### Registre global pour les symboles

Le registre global des symboles est une liste, initialement vide, dont les éléments ont la structure suivante :

| Nom du champ | Valeur |
| --- | --- |
| [[key]] | Une chaîne de caractères représentant la clé pour identifier un symbole en particulier. |
| [[symbol]] | Un symbole enregistré de façon globale. |

Exemples
--------


```js
Symbol.for("toto"); // crée un nouveau symbole global
Symbol.for("toto"); // renvoie le symbole déjà existant

// Globalement on a un symbole par clé, localement non
Symbol.for("machin") === Symbol.for("machin"); // true
Symbol("machin") === Symbol("machin"); // false

// La clé sert également de description
var sym = Symbol.for("mario");
sym.toString(); // "Symbol(mario)"
```


Afin d'éviter des conflits entre les clés des symboles globaux liés à votre application et les autres symboles potentiels (bibliothèques externes, etc...), il peut être judicieux de les préfixer :


```js
Symbol.for("mdn.toto");
Symbol.for("mdn.machin");
```

Spécifications
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.for |

Compatibilité des navigateurs
-----------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Voir aussi
----------

* `Symbol.keyFor()`
Symbol.match
============

Le symbole **`Symbol.match`** définit la correspondance d'une expression rationnelle par rapport à une chaîne de caractères. Cette fonction est appelée par la méthode `String.prototype.match()`.

Exemple interactif
------------------

Description
-----------

Cette fonction est également utilisée pour identifier les objets qui jouent un rôle avec les expressions rationnelles. Ainsi, les méthodes `String.prototype.startsWith()`, `String.prototype.endsWith()` et `String.prototype.includes()` vérifient si leur premier argument est une expression rationnelle et lèvent une exception `TypeError` si c'est le cas. Si le symbole `match` est modifié et vaut une valeur `false` (ou équivalente), cela indique que l'objet ne doit pas être utilisé comme une expression rationnelle.

| Attributs de `Symbol.match` |
| --- |
| Écrivable | Non |
| Énumérable | Non |
| Configurable | Non |

Exemples
--------

Le code suivant renverra une exception `TypeError` :


```js
"/truc/".startsWith(/truc/);

// lève une TypeError car /truc/
// est une expression rationnelle
// et que Symbol.match n'a pas été modifié.
```


Cependant, si `Symbol.match` vaut `false`, cette vérification `isRegExp` indiquera que l'objet à prendre en compte n'est pas une expression rationnelle. Les méthodes `startsWith` et `endsWith` ne déclencheront donc pas d'exception `TypeError`.


```js
var re = /toto/;
re[Symbol.match] = false;
"/toto/".startsWith(re); // true
"/truc/".endsWith(re); // false
```

Spécifications
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.match |

Compatibilité des navigateurs
-----------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Voir aussi
----------

* `Symbol.replace`
* `Symbol.search`
* `Symbol.split`
* `RegExp.prototype[@@match]()`
Symbol.species
==============

Le symbole **`Symbol.species`** correspond à une fonction utilisée comme constructeur pour créer des objets dérivés.

Exemple interactif
------------------

Description
-----------

L'accesseur `species` permettent aux classes filles de surcharger le constructeur par défaut des objets.

| Attributs de `Symbol.species` |
| --- |
| Écrivable | Non |
| Énumérable | Non |
| Configurable | Non |

Exemples
--------

Dans certains cas, vous pouvez avoir besoin de renvoyer `Array` pour les objets de votre classe dérivée `MonArray`. Cela permet par exemple d'utiliser le constructeur par défaut lors d'un appel à `map()`. De cette façon, ces méthodes renverront un objet `Array` plutôt qu'un objet `MonArray`. Grâce au symbole `species`, vous pouvez donc faire :


```js
class MonArray extends Array {
  // On surcharge species avec le constructeur parent Array
  static get [Symbol.species]() {
    return Array;
  }
}
var a = new MonArray(1, 2, 3);
var mapped = a.map((x) => x \* x);

console.log(mapped instanceof MonArray); // false
console.log(mapped instanceof Array); // true
```

Spécifications
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.species |

Compatibilité des navigateurs
-----------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Voir aussi
----------

* `Map[@@species]`
* `Set[@@species]`
Symbol.search
=============

Le symbole connu **`Symbol.search`** définit la méthode qui renvoie l'indice indiquant la position d'une correspondance trouvée dans une chaîne de caractères grâce à une expression rationnelle. Cette fonction est appelée par la méthode `String.prototype.search()`.

Pour plus d'informations, se référer aux pages sur `RegExp.prototype[@@search]()` et `String.prototype.search()`.

Exemple interactif
------------------

| Attributs de `Symbol.search` |
| --- |
| Écrivable | Non |
| Énumérable | Non |
| Configurable | Non |

Spécifications
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.search |

Compatibilité des navigateurs
-----------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Voir aussi
----------

* `Symbol.match`
* `Symbol.replace`
* `Symbol.split`
* `RegExp.prototype[@@search]()`
Symbol.iterator
===============

Le symbole **`Symbol.iterator`** définit l'itérateur par défaut d'un objet. C'est l'itérateur qui sera utilisé par `for...of`.

Exemple interactif
------------------

Description
-----------

Lorsqu'on doit itérer sur un objet (par exemple avec une boucle `for..of`), sa méthode `@@iterator` est appelée sans argument et l'itérateur renvoyé par la méthode est utilisé pour récupérer les valeurs sur lesquelles itérer.

Certains types natifs possèdent un comportement par défaut pour l'itération, d'autres types (tels qu'`Object`) n'ont pas de tel comportement. Les types natifs qui disposent d'une méthode `@@iterator` sont :

* `Array.prototype[@@iterator]()`
* `TypedArray.prototype[@@iterator]()`
* `String.prototype[@@iterator]()`
* `Map.prototype[@@iterator]()`
* `Set.prototype[@@iterator]()`

Pour plus d'informations, voir aussi la page sur les protocoles d'itération.

| Attributs de `Symbol.iterator` |
| --- |
| Écrivable | Non |
| Énumérable | Non |
| Configurable | Non |

Exemples
--------

### Itérables définis par l'utilisateur

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


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


On peut également définir ces itérables via des propriétés calculées dans des déclarations de classe ou dans des littéraux objets :


```js
class Toto {
  \*[Symbol.iterator] () {
    yield 1;
    yield 2;
    yield 3;
  }
}

const monObj = {
  \*[Symbol.iterator] () {
    yield "a";
    yield "b";
  }
}

[... new Toto] // [1, 2, 3]
[... monObj]   // ["a", "b"]
```

### Itérables mal-formés

Si la méthode `@@iterator` d'un itérable ne renvoie pas un itérateur, on dira que c'est un itérable mal-formé. Utiliser un tel itérable peut provoquer des erreurs lors de l'exécution :


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

Spécifications
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.iterator |

Compatibilité des navigateurs
-----------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Voir aussi
----------

* Les protocoles d'itération
* `Array.prototype[@@iterator]()`
* `TypedArray.prototype[@@iterator]()`
* `String.prototype[@@iterator]()`
* `Map.prototype[@@iterator]()`
* `Set.prototype[@@iterator]()`
Symbol.matchAll
===============

Le symbole connu **`Symbol.matchAll`** renvoie un itérateur qui fournit l'ensemble des correspondances entre une expression rationnelle et une chaîne de caractères. Cette fonction est implicitement appelée par la méthode `String.prototype.matchAll()`.

Exemple interactif
------------------

Description
-----------

Ce symbole est utilisé par `String.prototype.matchAll()` et plus particulièrement par `RegExp.prototype[@@matchAll]()`. Les deux lignes qui suivent renverront le même résultat :


```js
"abc".matchAll(/a/);

/a/[Symbol.matchAll]("abc");
```


Cette méthode existe afin de personnaliser le comportement des correspondances pour les sous-classes de `RegExp`.

| Attributs de `Symbol.matchAll` |
| --- |
| Écrivable | Non |
| Énumérable | Non |
| Configurable | Non |

Exemples
--------

Voir les pages `String.prototype.matchAll()` et `RegExp.prototype[@@matchAll]()` pour plus d'exemples.

Spécifications
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.matchall |

Compatibilité des navigateurs
-----------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Voir aussi
----------

* `String.prototype.matchAll()`
* `RegExp.prototype[@@matchAll]()`
Symbol.toPrimitive
==================

Le symbole « connu » **`Symbol.toPrimitive`** définit une fonction qui est appelée pour convertir un objet en une valeur primitive.

Exemple interactif
------------------

Description
-----------

Lorsqu'on convertit un objet en une valeur primitive et que l'objet possède une propriété `Symbol.toPrimitive` dont la valeur est une fonction, la fonction est appelée avec une chaîne de caractère (`hint`) qui définit le type qu'on privilégie pour la valeur primitive. L'argument `hint` peut prendre l'une des valeurs suivantes : `"number"`, `"string"` ou `"default"`.

| Attributs de `Symbol.toPrimitive` |
| --- |
| Écrivable | Non |
| Énumérable | Non |
| Configurable | Non |

Exemples
--------

Dans l'exemple qui suit, on voit comment la propriété `Symbol.toPrimitive` peut modifier la valeur primitive obtenue lors de la conversion d'un objet.


```js
// Premier cas avec un objet sans Symbol.toPrimitive.
let obj1 = {};
console.log(+obj1); // NaN
console.log(`${obj1}`); // "[object Object]"
console.log(obj1 + ""); // "[object Object]"

// Second cas : l'objet a une propriété Symbol.toPrimitive
var obj2 = {
  [Symbol.toPrimitive](hint) {
    if (hint === "number") {
      return 10;
    }
    if (hint === "string") {
      return "coucou";
    }
    return true;
  },
};
console.log(+obj2); // 10 -- hint vaut "number"
console.log(`${obj2}`); // "coucou" -- hint vaut "string"
console.log(obj2 + ""); // true -- hint vaut "default"
```

Spécifications
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol.toprimitive |

Compatibilité des navigateurs
-----------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Voir aussi
----------

* `Date.prototype[@@toPrimitive]`
* `Symbol.prototype[@@toPrimitive]`
* `Object.prototype.toString()`
* `Object.prototype.valueOf()`