La méthodegroupToMap() permet de grouper les éléments du tableau appelant selon les valeurs renvoyées par la fonction de test passée en argument. L'objetMap renvoyé utilise les valeurs uniques fournies par la fonction de test comme clés, et les valeurs correspondantes sont des tableaux avec les éléments du groupe correspondant.

Cette méthode est notamment utile lorsqu'on veut grouper des éléments associés avec un objet, notamment lorsque cet objet évolue avec le temps. Si cet objet ne varie, vous pouvez à la place utiliser une chaîne de caractères comme clé de regroupement et utiliser la méthodeArray.prototype.group().

Syntaxe

// Fonction fléchéegroupToMap((element) => { /* … */ } )groupToMap((element, index) => { /* … */ } )groupToMap((element, index, array) => { /* … */ } )// Fonction de rappelgroupToMap(fnRappel)groupToMap(fnRappel, thisArg)// Fonction de rappel en incisegroupToMap(function(element) { /* … */ })groupToMap(function(element, index) { /* … */ })groupToMap(function(element, index, array) { /* … */ })groupToMap(function(element, index, array) { /* … */ }, thisArg)

Paramètres

fnRappel

La fonction à exécuter pour chaque élément du tableau.

Elle est appelée avec les arguments suivants :

element

La valeur de l'élément du tableau en cours de traitement.

index

L'indice de l'élément courant dans le tableau.

array

Le tableau sur lequelgroupToMap() a été appelée.

La valeur (que ce soit un objet ou une valeur primitive) renvoyée par la fonction de rappel indique le groupe de l'élément courant.

thisArgFacultatif

L'objet à utiliser comme valeur pourthis pourfnRappel.

Cet argument est ignoré pour les fonctions fléchées qui disposent de leur propre portée lexicale, utilisée à la place. Sinon, sithisArg n'est pas fourni, c'est la valeurthis de la portée d'exécution qui est appelée, ouundefined si la fonction est appelée enmode strict.

Valeur de retour

Un objetMap avec une clé pour chaque groupe, et la valeur qui correspond à chaque clé qui est un tableau contenant les éléments du tableau appelant pour ce groupe.

Exceptions

TypeError

La fonction de rappel fournie en argument n'est pas appelable.

Description

La méthodegroup() exécute la fonctionfnRappel une fois pour chaque indice du tableau. La fonction de rappel renvoie une valeur indiquant le groupe de l'élément correspondant. Les valeurs renvoyées parfnRappel sont utilisées comme clés pour l'objetMap renvoyé pargroupToMap(). Chaque clé a comme valeur un tableau contenant les éléments pour lesquels la fonction de rappel a renvoyé la même valeur.

fnRappel est appelée pourchaque indice du tableau et pas uniquement pour ceux pour lesquels une valeur a été affectée. Les emplacements vides destableaux creux se comportent comme avecundefined.

fnRappel est appelée avec la valeur de l'élément courant, l'indice de cet élément, ainsi que le tableau complet. Bien que les groupes dépendent souvent de la valeur de l'élément courant, il est possible d'implémenter des stratégies de groupement basées sur les valeurs des autres éléments du tableau.

Si un paramètrethisArg est fourni à la méthodegroupToMap(), il sera utilisé comme valeur pourthis à chaque appel defnRappel. Si ce paramètre n'est pas fourni, c'estundefined qui sera utilisé.

La méthodegroupToMap() estune méthode de copie. Elle ne modifie pas le tableau courant (this) mais renvoie un objetMap dont les valeurs des clés contiennent les mêmes éléments que ceux du tableau d'origine. On notera donc que laMap renvoyée référence lesmêmes éléments que ceux du tableau original et pas descopies profondes. Modifier la structure interne de ces éléments se reflètera sur le tableau original et sur laMap renvoyée.

La méthodegroupToMap() estgénérique. Elle s'attend uniquement à ce que la valeurthis ait une propriétélength et des propriétés dont les clés sont des entiers.

Cette méthode s'avère utile lorsqu'on veut regrouper les informations associées à un objet donné qui peut évoluer au cours du temps. En effet, si l'objet est modifié, il pourra toujours être utilisé comme clé pour laMap renvoyée. En revanche, si on utilise une chaîne de caractères comme représentation d'un objet et qu'on l'utilise comme clé de groupement pourArray.prototype.group(), il faudra maintenir la correspondance entre l'objet original et sa représentation lorsque l'objet évolue.

Modifier le tableau avec la fonction de rappel

La méthodegroupToMap() ne modifie pas le tableau sur lequel elle est appelée, mais la fonction fournie pourfnRappel peut le modifier. Les éléments traités pargroupToMap() sont fixésavant le premier appel àfnRappel. Ainsi :

• fnRappel ne parcourra pas les éléments ajoutés après le début de l'appel àgroupToMap().
• Les éléments qui sont affectés à des indices ayant déjà été visités ne seront pas revus parfnRappel.
• Les éléments qui sont affectés à des indices en dehors de l'intervalle du tableau ne seront pas parcourus parfnRappel.
• Si un élément existant du tableau et qui n'a pas encore été traité mais est modifié parfnRappel, la valeur qui sera passée àfnRappel sera la valeur au moment oùgroupToMap() visite l'indice de l'élément.
• Les éléments qui sontsupprimés avecdelete sont tout de même parcourus.

Exemples

UtilisergroupToMap()

On définit un tableau contenant des objets qui représentent un inventaire alimentaire. Chaque type d'aliment a une propriététype et une propriétéquantite.

const inventaire = [  { nom: "asperge", type: "legume", quantite: 9 },  { nom: "banane", type: "fruit", quantite: 5 },  { nom: "agneau", type: "viande", quantite: 23 },  { nom: "cerise", type: "fruit", quantite: 12 },  { nom: "poisson", type: "viande", quantite: 22 },];

Dans le code qui suit, on utilisegroupToMap() avec une fonction fléchée qui renvoie les clés nomméesrestock ousuffisant, selon que l'élément a une propriétéquantite < 6.L'objetresultat est uneMap et il faut donc appeler la méthodeget() avec la clé correspondante pour avoir le tableau du groupe.

const restock = { restock: true };const suffisant = { restock: false };const resultat = inventaire.groupToMap(({ quantite }) =>  quantite < 6 ? restock : suffisant,);console.log(resultat.get(restock));// résultat attendu : Array [Object { nom: "banane", type: "fruit", quantite: 5 }]

Ici, l'argument{ quantite } passé à la fonction est un exemple dedécomposition objet pour les arguments d'une fonction. Cela récupère la propriétéquantite de l'objet passé en paramètre et affecte cette valeur à une variable nomméequantite dans le corps de la fonction. Il s'agit d'une écriture concise pour accéder aux valeurs des propriétés pertinentes d'un objet dans une fonction.

La clé d'un objetMap peut être modifiée et continuer d'être utilisée. Toutefois, on ne peut pas recréer un autre objet ayant la même structure que la clé et l'utiliser. Il est donc important que tout ce qui doit utiliser laMap garde une référence vers ses clés.

// La clé peut être modifiée et continuer d'être utiliséerestock["rapide"] = true;console.log(resultat.get(restock));// résultat attendu : Array [Object { nom: "banane", type: "fruit", quantite: 5 }]// Une nouvelle clé ne peut pas être utilisée, même si elle a la même structure !const restock2 = { restock: true };console.log(resultat.get(restock2));// résultat attendu : undefined

UtilisergroupToMap() sur des tableaux creux

Lorsqu'on utilisegroupToMap() surun tableau creux, les emplacements vides du tableau sont considérés comme ayant la valeurundefined.

console.log([1, , 3].groupToMap((x) => x));// Map { 1 => [1], undefined => [undefined], 3 => [3] }

AppelergroupToMap() sur des objets qui ne sont pas des tableaux

La méthodegroupToMap() lit la propriétélength dethis puis parcourt les propriétés dont les clés sont des nombres entiers.

const semblableTableau = {  length: 3,  0: 2,  1: 3,  2: 4,};console.log(Array.prototype.groupToMap.call(semblableTableau, (x) => x % 2));// Map { 0 => [2, 4], 1 => [3] }

Spécifications

Compatibilité des navigateurs

Voir aussi

• Array.prototype.group()
• Une prothèse d'émulation deArray.prototype.groupToMap() dans la bibliothèque tiercecore-js