Array.prototype.groupToMap()

Syntaxe

// Fonction fléchée
groupToMap((element) => { /* … */ } )
groupToMap((element, index) => { /* … */ } )
groupToMap((element, index, array) => { /* … */ } )

// Fonction de rappel
groupToMap(fnRappel)
groupToMap(fnRappel, thisArg)

// Fonction de rappel en incise
groupToMap(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 lequel groupToMap() 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.

thisArg Facultatif

L'objet à utiliser comme valeur pour this pour fnRappel.

Cet argument est ignoré pour les fonctions fléchées qui disposent de leur propre portée lexicale, utilisée à la place. Sinon, si thisArg n'est pas fourni, c'est la valeur this de la portée d'exécution qui est appelée, ou undefined si la fonction est appelée en mode strict.

Valeur de retour

Un objet Map 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éthode group() exécute la fonction fnRappel 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 par fnRappel sont utilisées comme clés pour l'objet Map renvoyé par groupToMap(). 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 pour chaque indice du tableau et pas uniquement pour ceux pour lesquels une valeur a été affectée. Les emplacements vides des tableaux creux se comportent comme avec undefined.

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ètre thisArg est fourni à la méthode groupToMap(), il sera utilisé comme valeur pour this à chaque appel de fnRappel. Si ce paramètre n'est pas fourni, c'est undefined qui sera utilisé.

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

La méthode groupToMap() est générique. Elle s'attend uniquement à ce que la valeur this 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 la Map 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 pour Array.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éthode groupToMap() ne modifie pas le tableau sur lequel elle est appelée, mais la fonction fournie pour fnRappel peut le modifier. Les éléments traités par groupToMap() sont fixés avant 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 par fnRappel.
• Les éléments qui sont affectés à des indices en dehors de l'intervalle du tableau ne seront pas parcourus par fnRappel.
• Si un élément existant du tableau et qui n'a pas encore été traité mais est modifié par fnRappel, 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 sont supprimés avec delete sont tout de même parcourus.

Exemples

Utiliser groupToMap()

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 utilise groupToMap() avec une fonction fléchée qui renvoie les clés nommées restock ou suffisant, selon que l'élément a une propriété quantite < 6. L'objet resultat est une Map et il faut donc appeler la méthode get() 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 de dé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ée quantite 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 objet Map 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 la Map garde une référence vers ses clés.

// La clé peut être modifiée et continuer d'être utilisée
restock["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

Utiliser groupToMap() sur des tableaux creux

Lorsqu'on utilise groupToMap() sur un tableau creux, les emplacements vides du tableau sont considérés comme ayant la valeur undefined.

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

Appeler groupToMap() sur des objets qui ne sont pas des tableaux

La méthode groupToMap() lit la propriété length de this 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 de Array.prototype.groupToMap() dans la bibliothèque tierce core-js