Map

L'objet Map représente un dictionnaire, autrement dit une carte de clés/valeurs. N'importe quelle valeur valable en JavaScript (que ce soit les objets ou les valeurs de types primitifs) peut être utilisée comme clé ou comme valeur.

Syntaxe

new Map([itérable])

Paramètres

itérable

Un tableau Array ou tout autre objet itérable dont les éléments sont des paires clé/valeur (des objets Arrays à deux éléments). Chaque paire clé/valeur sera ajoutée au nouvel objet Map. null est traité comme undefined.

Description

Un objet Map permet de retrouver ses éléments dans leur ordre d'insertion. Par exemple, une boucle for...of renverra un tableau de [clé, valeur] pour chaque itération.

Égalité des clés

L'égalité des clés est testée avec l'algorithme basé sur l'égalité de valeurs :

• NaN est considéré égal à NaN (bien que, pour l'égalité stricte NaN !== NaN)
• les autres valeurs sont considérées égales au sens de l'égalité stricte (l'opérateur  ===).

Dans les versions précédentes des brouillons ECMAScript 2015 (ES6) -0 et +0 étaient considérés différents (bien que -0 === +0), ceci a été changé dans les versions ultérieures et a été adapté avec Gecko 29 (Firefox 29 / Thunderbird 29 / SeaMonkey 2.26) (bug 952870) et une version nocturne de Chrome.

Comparaison entre objets et maps

Les objets sont similaires aux Maps, chacun manipulant des clés associées à des valeurs, récupérant ces valeurs, supprimant des clés... Il n'y avait auparavant pas d'alternatives natives et c'est pourquoi, historiquement, les objets JavaScript ont été utilisés comme des Maps. Malgré tout, il y a des différences importantes entre Objects et Maps qui permettent de distinguer une utilisation des objets Map plus efficace :

• Un Object possède un prototype, il peut donc y avoir certaines clés par défaut qui peuvent entrer en collision avec les clés qu'on souhaite créer. On peut contourner cela en utilisant map = Object.create(null).
• Les clés d'un Object sont des chaînes de caractères, alors que pour une Map ça peut être n'importe quelle valeur.
• Il est possible d'obtenir facilement la taille d'une Map avec size. En revanche, pour un Object il faudra compter « manuellement ».

Il est conseillé d'utiliser des Maps plutôt que des objets quand les clés sont inconnues au moment de l'exécution et lorsque toutes les clés sont du même type et que toutes les valeurs sont du même type.

Cela ne signifie pas que Map doit être utilisé partout. Dans la plupart des scénarios, les objets restent une solution valide. Les instances de Map sont uniquement utiles pour construire des collections et il faut adapter le code qui utilisait des objets pour stocker de telles structures. Les objets doivent être utilisés comme des enregistrements, avec des champs et des méthodes. Si vous n'arrivez pas à déterminer lequel des deux utiliser, posez-vous ces questions :

• Est-ce que les clés sont inconnues avant l'exécution ? doit-on les parcourir dynamiquement ?
• Est-ce que toutes les valeurs ont le même type ? est-ce qu'elles peuvent être utilisées les unes à la place des autres ?
• Est-ce que les clés ne sont pas nécessairement des chaînes ?
• Est-ce que des paires clés-valeurs sont fréquemment ajoutées ou retirées ?
• Faut-il pouvoir utiliser un nombre arbitraire (facilement adaptable) de clés-valeurs ?
• Itère-t-on sur cette collection ?

Si vous répondez favorablement à la plupart de ces questions, cela signifie que vous manipulez une collection et qu'une Map sera préférable. Il est conseillé d'utiliser des objets génériques quand on retrouve une certaine logique pour chacun des éléments individuels.

Propriétés

Map.length

La valeur de la propriété length est 0.

get Map[@@species]

La fonction constructeur utilisée pour créer des objets dérivées.

Map.prototype

Représente le prototype du constructeur Map. Permet l'addition de propriétés à tous les objets Map.

Instances de Map

Toutes les instances de Map héritent de Map.prototype.

Propriétés

Méthodes

Exemples

Utiliser un objet Map

var maMap = new Map();

var objetClé = {},
    fonctionClé = function () {},
    chaineClé = "une chaîne";

// définir les valeurs
maMap.set(chaineClé, "valeur associée à 'une chaîne'");
maMap.set(objetClé, "valeur associée à objetClé");
maMap.set(fonctionClé, "valeur associée à fonctionClé");

maMap.size; // 3

// récupérer les valeurs
maMap.get(chaineClé);    // "valeur associée à 'une chaîne'"
maMap.get(objetClé);     // "valeur associée à objetClé"
maMap.get(fonctionClé);  // "valeur associée à fonctionClé"

maMap.get("une chaîne"); // "valeur associée à 'une chaîne'"
                         // car chaineClé === 'une chaîne'
maMap.get({});           // indéfini car objetClé !== {}
maMap.get(function() {}) // indéfini car fonctionClé !== function () {}

Utiliser NaN comme clé

NaN peut être utilisé comme une clé. Bien que NaN ne soit pas strictement égal à lui-même (NaN !== NaN est vérifié), on peut bâtir l'exemple suivant car on ne peut pas distinguer deux valeurs NaN :

var maMap = new Map();
maMap.set(NaN, "not a number");

maMap.get(NaN); // "not a number"

var autreNaN = Number("toto");
maMap.get(autreNaN); // "not a number"

Parcourir des objets Maps avec for..of

Il est possible de parcourir les objets Map grâce à des boucles for..of :

var maMap = new Map();
maMap.set(0, "zéro");
maMap.set(1, "un");
for (var [clé, valeur] of maMap) {
  console.log(clé + " = " + valeur);
}
// On aura 2 lignes : la première avec "0 = zéro"
// la seconde avec "1 = un"

for (var clé of maMap.keys()) {
  console.log(clé);
}
// On aura 2 lignes : la première avec "0"
// et la seconde avec "1"

for (var valeur of maMap.values()) {
  console.log(valeur);
}
// On aura 2 lignes : la première avec "zéro"
// et la seconde avec "un"

for (var [clé, valeur] of maMap.entries()) {
  console.log(clé + " = " + valeur);
}
// On aura 2 lignes : la première avec "0 = zéro"
// la seconde avec "1 = un"

maMap.forEach(function(valeur, clé) {
  console.log(clé + " = " + valeur);
});
// On aura 2 lignes : la première avec "0 = zéro"
// la seconde avec "1 = un"

Relation avec les objets Array

var tableauCléValeur = [["clé1", "valeur1"], ["clé2", "valeur2"]];

// On utilise le constructeur Map
// pour transformer un tableau de clés/valeurs
// en un objet map
var maMap = new Map(tableauCléValeur);

maMap.get("clé1"); // renvoie "valeur1"

// On utilise la fonction Array.from pour transformer
// une map en un tableau de clés/valeurs
console.log(Array.from(maMap)); // affichera la même chose que tableauCléValeur

// On peut aussi l'utiliser pour n'extraire que les clés
// ou les valeurs et créer le tableau associé
console.log(Array.from(maMap.keys())); // affichera ["clé1", "clé2"]

Spécifications

Compatibilité des navigateurs

[1] Cette fonctionnalité est disponible dans Chrome derrière un réglage utilisateur. Sous chrome://flags, activer l'élément « Activer la fonctionnalité expérimentale JavaScript ».

Voir aussi

• Le bug sur Map et Set pour Mozilla
• La proposition ECMAScript Harmony
• Set
• WeakMap
• WeakSet