Map

Об'єкт Map зберігає пари ключ-значення. Будь-яке значення (і об'єкт, і примітивне значення) може бути використано і як ключ, і як значення.

Синтаксис

new Map([iterable])

Параметри

iterable

Array або інший об'єкт, що перебирається, чиї елементи є парами ключ-значення (масиви з двома елементами, наприклад, [[1, 'one'], [2, 'two']] ). Кожна пара ключ-значення додається до нового Map; значення null вважаються undefined.

Опис

Об'єкт Map перебирає свої елементи у порядку їх введення — цикл for...of повертає масив [ключ, значення] під час кожної ітерації.

Слід зазначити, що Map, що є Map'ом об'єкта, especially a dictionary of dictionaries, буде перебиратися у порядку додавання елементів в об'єкт - у довільному порядку і не упорядковано.

Еквівалентність ключів

Еквівалентність ключів основана на алгоритмі "SameValueZero": NaN вважається NaN (хоча, NaN !== NaN) і всі інші значення вважаються еквівалентними згідно семантики оператора ===. У сучасній версії сецифікації ECMAScript -0 та +0 вважаються еквівалентними, хоча у попередніх версіях було інакше. Більш детально дивіться "Value equality for -0 and 0" у таблиці сумісності браузерів.

Порівняння об'єктів та maps

Objects are similar to Maps in that both let you set keys to values, retrieve those values, delete keys, and detect whether something is stored at a key. Because of this (and because there were no built-in alternatives), Objects have been used as Maps historically; however, there are important differences that make using a Map preferable in certain cases:

• The keys of an Object are Strings and Symbols, whereas they can be any value for a Map, including functions, objects, and any primitive.
• You can get the size of a Map easily with the size property, while the number of properties in an Object must be determined manually.
• A Map is an iterable and can thus be directly iterated, whereas iterating over an Object requires obtaining its keys in some fashion and iterating over them.
• An Object has a prototype, so there are default keys in the map that could collide with your keys if you're not careful. As of ES5 this can be bypassed by using map = Object.create(null), but this is seldom done.
• A Map may perform better in scenarios involving frequent addition and removal of key pairs.

Properties

Map.length

The value of the length property is 0.

get Map[@@species]

The constructor function that is used to create derived objects.

Map.prototype

Represents the prototype for the Map constructor. Allows the addition of properties to all Map objects.

Map instances

All Map instances inherit from Map.prototype.

Properties

Methods

Examples

Using the Map object

var myMap = new Map();

var keyString = 'a string',
    keyObj = {},
    keyFunc = function() {};

// setting the values
myMap.set(keyString, "value associated with 'a string'");
myMap.set(keyObj, 'value associated with keyObj');
myMap.set(keyFunc, 'value associated with keyFunc');

myMap.size; // 3

// getting the values
myMap.get(keyString);    // "value associated with 'a string'"
myMap.get(keyObj);       // "value associated with keyObj"
myMap.get(keyFunc);      // "value associated with keyFunc"

myMap.get('a string');   // "value associated with 'a string'"
                         // because keyString === 'a string'
myMap.get({});           // undefined, because keyObj !== {}
myMap.get(function() {}) // undefined, because keyFunc !== function () {}

Using NaN as Map keys

NaN can also be used as a key. Even though every NaN is not equal to itself (NaN !== NaN is true), the following example works because NaNs are indistinguishable from each other:

var myMap = new Map();
myMap.set(NaN, 'not a number');

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

var otherNaN = Number('foo');
myMap.get(otherNaN); // "not a number"

Iterating Maps with for..of

Maps can be iterated using a for..of loop:

var myMap = new Map();
myMap.set(0, 'zero');
myMap.set(1, 'one');
for (var [key, value] of myMap) {
  console.log(key + ' = ' + value);
}
// 0 = zero
// 1 = one

for (var key of myMap.keys()) {
  console.log(key);
}
// 0
// 1

for (var value of myMap.values()) {
  console.log(value);
}
// zero
// one

for (var [key, value] of myMap.entries()) {
  console.log(key + ' = ' + value);
}
// 0 = zero
// 1 = one

Iterating Maps with forEach()

Maps can be iterated using the forEach() method:

myMap.forEach(function(value, key) {
  console.log(key + ' = ' + value);
});
// Will show 2 logs; first with "0 = zero" and second with "1 = one"

Relation with Array objects

var kvArray = [['key1', 'value1'], ['key2', 'value2']];

// Use the regular Map constructor to transform a 2D key-value Array into a map
var myMap = new Map(kvArray);

myMap.get('key1'); // returns "value1"

// Use the Array.from function to transform a map into a 2D key-value Array
console.log(Array.from(myMap)); // Will show you exactly the same Array as kvArray

// Or use the keys or values iterators and convert them to an array
console.log(Array.from(myMap.keys())); // Will show ["key1", "key2"]

Specifications

Browser compatibility

See also

• Map and Set bug at Mozilla
• ECMAScript Harmony proposal
• Set
• WeakMap
• WeakSet