Map

Exemple interactif

const map = new Map();

map.set("a", 1);
map.set("b", 2);
map.set("c", 3);

console.log(map.get("a"));
// Sortie attendue : 1

map.set("a", 97);

console.log(map.get("a"));
// Sortie attendue : 97

console.log(map.size);
// Sortie attendue : 3

map.delete("b");

console.log(map.size);
// Sortie attendue : 2

Description

Les objets Map sont des collections de paires clé-valeur. Une clé dans Map ne peut apparaître qu'une seule fois ; elle est unique dans la collection de Map. Un objet Map est itéré par paires clé-valeur — une boucle for...of retourne un tableau à deux éléments [key, value] pour chaque itération. L'itération se fait dans l'ordre d'insertion, ce qui correspond à l'ordre dans lequel chaque paire clé-valeur a été insérée pour la première fois dans la map par la méthode set() (c'est-à-dire qu'il n'y avait pas de clé avec la même valeur déjà dans la map lorsque set() a été appelée).

La spécification exige que les tables associatives soient implémentées « de sorte qu'elles fournissent, en moyenne, des temps d'accès sous-linéaires par rapport au nombre d'éléments de la collection ». Elles peuvent donc être représentées en interne par une table de hachage (avec une recherche en O(1)), un arbre de recherche (avec une recherche en O(log(N))) ou toute autre structure de données, tant que la complexité est meilleure que O(N).

Égalité des clés

L'égalité de valeur est basée sur l'algorithme SameValueZero. (Auparavant, elle utilisait SameValue, qui traitait 0 et -0 comme deux valeurs différentes. Voir la compatibilité des navigateurs.) Cela signifie que NaN est considéré comme égal à NaN (même si NaN !== NaN) et toutes les autres valeurs sont considérées comme égales selon la sémantique de l'opérateur ===. De plus, pour les clés d'objet, l'égalité est basée sur l'identité de l'objet. Elles sont comparées par référence, et non par valeur. Voir Utiliser l'objet Map pour des exemples.

Comparaison entre objets et Map

Object est similaire à Map — les deux permettent d'associer des clés à des valeurs, de récupérer ces valeurs, de supprimer des clés et de détecter si quelque chose est stocké sous une clé. Pour cette raison (et parce qu'il n'existait pas d'alternatives intégrées), Object a été historiquement utilisé comme Map.

Toutefois, il existe des différences importantes qui font que Map se démarque et peut être préférable dans certains cas :

Ajouter des propriétés objet

Les structures Map sont également des objets et il est donc possible de leur rajouter des propriétés objets. Attention toutefois, car cela peut être source de confusion.

Ainsi, on pourra faire :

const mauvaiseMap = new Map();
mauvaiseMap["bla"] = "blaa";
mauvaiseMap["bla2"] = "blaaa2";

console.log(mauvaiseMap); // Map { bla: 'blaa', bla2: 'blaaa2' }

Mais ces instructions n'interagissent pas avec la structure Map, elles ne font qu'ajouter des propriétés objet. La valeur associée à la clé "bla" n'est pas stockée dans la Map. Ainsi, si on utilise les méthodes de Map, cela échouera :

mauvaiseMap.has("bla"); // false
mauvaiseMap.delete("bla"); // false
console.log(mauvaiseMap); // Map { bla: 'blaa', bla2: 'blaaa2' }

Pour stocker des données dans une structure Map, on utilisera plutôt la méthode set(cle, valeur).

const contacts = new Map();
contacts.set("Jessie", {
  telephone: "01 99 00 12 34",
  adresse: "1 Rue de l'avenue",
});
contacts.has("Jessie"); // true
contacts.get("James"); // undefined
contacts.set("James", {
  telephone: "06 39 98 78 89",
  adresse: "3 Chemin du Parc",
});
contacts.get("Jessie"); // {telephone: "01 99 00 12 34", adresse: "1 Rue de l'avenue"}
contacts.delete("Miaouss"); // false
contacts.delete("Jessie"); // true
console.log(contacts.size); // 1

API de navigateur similaires à Map

Objets Map du navigateur (ou « objets semblables à Map ») sont des interfaces API Web qui se comportent de nombreuses façons comme une Map.

Comme Map, les entrées peuvent être parcourues dans le même ordre que celui de leur ajout à l'objet. Les objets de type Map et Map lui-même possèdent également des propriétés et des méthodes portant les mêmes noms et ayant le même comportement. Cependant, contrairement à Map, ils n'autorisent que des types prédéfinis spécifiques pour les clés et les valeurs de chaque entrée.

Les types autorisés sont définis dans la définition IDL de la spécification. Par exemple, RTCStatsReport est un objet de type Map qui doit utiliser des chaînes de caractères pour les clés et des objets pour les valeurs. Ceci est défini dans l'IDL de la spécification ci‑dessous :

interface RTCStatsReport {
  readonly maplike<DOMString, object>;
};

Les objets de type Map sont soit en lecture seule, soit en lecture-écriture (voir le mot-clé readonly dans l'IDL ci‑dessus).

• Les objets de type Map en lecture seule possèdent la propriété size, et les méthodes : entries(), forEach(), get(), has(), keys(), values(), et Symbol.iterator().
• Les objets de type Map modifiables possèdent en plus les méthodes : clear(), delete(), et set().

Les méthodes et propriétés ont le même comportement que leurs équivalents dans Map, sauf pour la restriction sur les types des clés et des valeurs.

Les exemples suivants sont des objets de navigateur de type Map en lecture seule :

• AudioParamMap
• CSSFontFeatureValuesMap
• EventCounts
• KeyboardLayoutMap
• MIDIInputMap
• MIDIOutputMap
• RTCStatsReport

Constructeur

Map()

Crée un nouvel objet Map.

Propriétés statiques

Map[Symbol.species]

La fonction de construction utilisée pour créer les objets dérivés.

Méthodes statiques

Map.groupBy()

Regroupe les éléments d'un itérable donné en utilisant les valeurs retournées par une fonction de rappel fournie. La Map finale retournée utilise les valeurs uniques de la fonction de test comme clés, ce qui permet d'obtenir le tableau d'éléments de chaque groupe.

Propriétés d'instances

Ces propriétés sont définies sur Map.prototype et sont partagées par toutes les instances de Map.

Map.prototype.constructor

La fonction de construction qui a créé l'objet instance. Pour les instances de Map, la valeur initiale est le constructeur Map().

Map.prototype.size

Retourne le nombre de paires clé/valeur contenues dans l'objet Map.

Map.prototype[Symbol.toStringTag]

La valeur initiale de la propriété [Symbol.toStringTag] est la chaîne de caractères "Map". Cette propriété est utilisée dans Object.prototype.toString().

Méthodes d'instances

Map.prototype.clear()

Supprime toutes les paires de clé/valeur de l'objet Map.

Map.prototype.delete()

Supprime l'entrée définie par la clé spécifiée de cet objet Map.

Map.prototype.entries()

Retourne un nouvel objet itérateur qui contient un tableau de [key, value] pour chaque élément de l'objet Map, dans leur ordre d'insertion.

Map.prototype.forEach()

Appelle la fonction callbackFn une fois pour chaque paire clé/valeur contenue dans l'objet Map, dans leur ordre d'insertion. Si un paramètre thisArg est fourni à forEach(), sa valeur sera utilisée comme valeur pour this lors de chaque appel.

Map.prototype.get()

Retourne la valeur associée à la clé passée en argument à la Map, ou undefined s'il n'y en a pas.

Map.prototype.getOrInsert()

Retourne la valeur correspondant à la clé définie dans cette Map. Si la clé n'est pas présente, elle insère une nouvelle entrée avec la clé et une valeur par défaut fournie, puis retourne la valeur insérée.

Map.prototype.getOrInsertComputed()

Retourne la valeur correspondant à la clé définie dans cette Map. Si la clé n'est pas présente, elle insère une nouvelle entrée avec la clé et une valeur par défaut calculée par un rappel fourni, puis retourne la valeur insérée.

Map.prototype.has()

Retourne un booléen indiquant s'il existe une valeur associée à la clé fournie par l'argument dans l'objet Map.

Map.prototype.keys()

Retourne un nouvel objet itérateur qui contient les clés pour chaque élément de l'objet Map, dans leur ordre d'insertion.

Map.prototype.set()

Ajoute une nouvelle entrée avec une clé et une valeur définie à cette Map, ou met à jour une entrée existante si la clé existe déjà.

Map.prototype.values()

Retourne un nouvel objet itérateur qui contient les valeurs pour chaque élément de l'objet Map, dans leur ordre d'insertion.

Map.prototype[@@iterator]()

Retourne un nouvel objet itérateur qui contient un tableau de [key, value] pour chaque élément de l'objet Map, dans leur ordre d'insertion.

Exemples

Utiliser l'objet Map

const maMap = new Map();

const cleChaine = "une chaîne de caractères";
const cleObjet = {};
const cleFonction = () => {};

// définir les valeurs
maMap.set(cleChaine, "valeur associée à 'une chaîne de caractères'");
maMap.set(cleObjet, "valeur associée à cleObjet");
maMap.set(cleFonction, "valeur associée à cleFonction");

console.log(maMap.size); // 3

// récupérer les valeurs
console.log(maMap.get(cleChaine)); // "valeur associée à 'une chaîne de caractères'"
console.log(maMap.get(cleObjet)); // "valeur associée à cleObjet"
console.log(maMap.get(cleFonction)); // "valeur associée à cleFonction"

console.log(maMap.get("une chaîne de caractères")); // "valeur associée à 'une chaîne de caractères'", parce que cleChaine === 'une chaîne de caractères'
console.log(maMap.get({})); // undefined, parce que cleObjet !== {}
console.log(maMap.get(() => {})); // undefined, parce que cleFonction !== () => {}

Utiliser NaN comme clés de Map

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

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

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

const 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 :

const maMap = new Map();
maMap.set(0, "zéro");
maMap.set(1, "un");

for (const [cle, valeur] of maMap) {
  console.log(`${cle} = ${valeur}`);
}
// "0 = zéro"
// "1 = un"

for (const cle of maMap.keys()) {
  console.log(cle);
}
// 0
// 1

for (const valeur of maMap.values()) {
  console.log(valeur);
}
// zéro
// un

for (const [cle, valeur] of maMap.entries()) {
  console.log(`${cle} = ${valeur}`);
}
// 0 = zéro
// 1 = un

Parcourir des objets Map avec forEach()

Il est aussi possible de parcourir des objets Map avec la méthode forEach() :

maMap.forEach(function (valeur, cle) {
  console.log(`${cle} = ${valeur}`);
});
// 0 = zéro
// 1 = un

Relation avec les objets Array

const paireCleValeur = [
  ["clé1", "valeur1"],
  ["clé2", "valeur2"],
];

// On utilise le constructeur Map
// pour transformer un tableau de clés/valeurs
// en un objet Map
const maMap = new Map(paireCleValeur);

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 paireCleValeur

// Avec une méthode plus concise grâce à la décomposition
console.log([...maMap]);

// 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"]

Cloner et fusionner des objets Map

Il est possible de cloner des Map comme on clone des tableaux :

const original = new Map([[1, "un"]]);

const clone = new Map(original);

console.log(clone.get(1)); // un
console.log(original === clone); // false (utile pour une comparaison superficielle)

Les tableaux associatifs peuvent être fusionnés, en conservant l'unicité des clés :

const premier = new Map([
  [1, "un"],
  [2, "deux"],
  [3, "trois"],
]);

const second = new Map([
  [1, "uno"],
  [2, "dos"],
]);

// Fusionner deux tableaux associatifs. La dernière clé répétée l'emporte.
// La syntaxe de décomposition convertit essentiellement un tableau associatif en un tableau
const fusion = new Map([...premier, ...second]);

console.log(fusion.get(1)); // uno
console.log(fusion.get(2)); // dos
console.log(fusion.get(3)); // trois

Il est également possible de fusionner des objets Map avec des objets Array :

const premier = new Map([
  [1, "un"],
  [2, "deux"],
  [3, "trois"],
]);

const second = new Map([
  [1, "uno"],
  [2, "dos"],
]);

// On peut fusionner des Maps avec un tableau.
// La dernière clé répétée l'emporte.
const fusion = new Map([...premier, ...second, [1, "eins"]]);

console.log(fusion.get(1)); // eins
console.log(fusion.get(2)); // dos
console.log(fusion.get(3)); // trois

Spécifications

Compatibilité des navigateurs

Voir aussi

• Prothèse d'émulation pour Map dans core-js ^(angl.)
• Prothèse d'émulation pour Map dans es-shims ^(angl.)
• L'objet Set
• L'objet WeakMap
• L'objet WeakSet