Map : Object

constructor iterable

Maps allow associating keys and values similar to normal Objects except Maps allow any Object to be used as a key instead of just Strings and Symbols. Maps use get() and set() methods to access the values stored in the Map. A Map are often called a HashTable or a Dictionary in other languages.

ECMAScript 2015 Spec

Constructors

new Map() : Map

Creates an empty Map.

Example:

var objectKey = { foo: 'bar' };

var x = new Map();
x.set(1, 'keys are not converted to strings');
x.set('1', 'this is stored separately than the previous value');
x.set(objectKey, ['you use arbitrary objects as keys and values']);

console.log(x.get(1));
console.log(x.get('1'));
console.log(x.get(objectKey));

Run

Results:

Spec

new Map(iterable : Object) : Map

Creates a Map by iterating over iterable and using the first element of the iterator value as the key and second element as the value.

Example:

var objectKey = { foo: 'bar' };

var fromArray = new Map([[0, 'array0'], [objectKey, 'array1']]);

console.log(fromArray.get(0));
console.log(fromArray.get(objectKey));
console.log();

var generator = function*() {
  yield [0, 'generator0'];
  yield [objectKey, 'generator1'];
};

var fromGenerator = new Map(generator());
console.log(fromGenerator.get(0));
console.log(fromGenerator.get(objectKey));

Run

Results:

Spec

Instance Properties

size : Number

The number of key/value pairs in this.

Example:

var x = new Map([['a', 'value A'], ['b', 'value B'], ['c', 'value C']]);

console.log(x.size);

x.set('d', 'value D');

console.log(x.size);

x.clear();

console.log(x.size);

Run

Results:

Spec

Instance Methods

clear() : undefined

Clears the key/value pairs from this.

Example:

var x = new Map([['a', 'value A'], ['b', 'value B'], ['c', 'value C']]);

console.log(x.size);

x.clear();

console.log(x.size);

Run

Results:

Spec

delete(key : Object) : Boolean

Removes key and its corresponding value from this. Returns true if key was in this before deleting it.

Example:

var x = new Map([['a', 'value A'], ['b', 'value B'], ['c', 'value C']]);

console.log('size before delete: ' + x.size);
console.log('deleted "a" = ' + x.delete('a'));

console.log('size after delete: ' + x.size);
console.log('value for "a" = ' + x.get('a'));

console.log('deleted "foo" = ' + x.delete('foo'));
console.log('size after delete: ' + x.size);

Run

Results:

Spec

entries() : Iterator<Array>

Returns an iterator of the index and items in this where the valuess of the iterator are of the form [key : Object, value : Object]. The entries function is also returned for this[Symbol.iterator] so you can iterate over this directly to get the entries. See also keys() and values().

Example:

var x = new Map([['a', 'value A'], ['b', 'value B'], ['c', 'value C']]);

// entries is returned by x[Symbol.iterator] so you can just 
// use x directly in the for (... of ...) loop
for (var value of x) {
  console.dir(value);
}

// You can iterate over entries explicitly
for (var entry of x.entries()) {
  console.dir(entry);
}

// Or access the iterator manually
var entries = x.entries();

console.dir(entries.next());
console.dir(entries.next());
console.dir(entries.next());
console.dir(entries.next());

Run

Results:

Spec

forEach(callback : Function, [thisArg : Object]) : undefined

callback(value : Object, key : Object, map : Map) : undefined

Calls callback for each key/value pair in this. The Map passed to callback is the this of the call to forEach.

Example:

var x = new Map([['a', 'value A'], ['b', 'value B'], ['c', 'value C']]);

x.forEach(function(value, key, map) {
  console.log('key: "' + key + '", value: "' + value + '"');
});

Run

Results:

Spec

get(key : Object) : Object

Returns the value stored for key. If no value is stored, returns undefined. See also has() and set().

Example:

var x = new Map([['a', 'value A'], ['b', 'value B'], ['c', 'value C']]);

console.log(x.get('a'));
console.log(x.get('b'));

// Notice the values stored in the map are not properties on
// the object. get() is the only way to retrieve the values.
console.log(x['b']);

Run

Results:

Spec

has(key : Object) : Boolean

Returns true if the map has a value stored for key.

Example:

var x = new Map([['a', 'value A'], ['b', 'value B'], ['c', 'value C']]);

console.log(x.has('a'));
console.log(x.has('foo'));

// has() lets you check if a value is stored, even if 
// the value is undefined
x.set('e', undefined);
console.log(x.has('e') + ' ' + x.get('e'));
console.log(x.has('f') + ' ' + x.get('f'));

Run

Results:

Spec

keys() : Iterator

Returns an iterator of the keys in this. See also entries() and values().

Example:

var x = new Map([['a', 'value A'], ['b', 'value B'], ['c', 'value C']]);

// Use for (... of ...) to loop over the iterator
for (var key of x.keys()) {
  console.dir(key);
}

// Or access the iterator manually
var keys = x.keys();

console.dir(keys.next());
console.dir(keys.next());
console.dir(keys.next());
console.dir(keys.next());

Run

Results:

Spec

set(key : Object, value : Object) : Map

Stores value in this at the specified key. If a value is already stored for that key, it is replaced with value. Returns this. See also get() and has().

Example:

var x = new Map([['a', 'value A'], ['b', 'value B'], ['c', 'value C']]);

console.log(x.get('a'));

x.set('a', 'a different value');
console.log(x.get('a'));

Run

Results:

Spec

values() : Iterator

Returns an iterator of the values in this. See also entries() and keys().

Example:

var x = new Map([['a', 'value A'], ['b', 'value B'], ['c', 'value C']]);

// Use for (... of ...) to loop over the iterator
for (var value of x.values()) {
  console.dir(value);
}

// Or access the iterator manually
var values = x.values();

console.dir(values.next());
console.dir(values.next());
console.dir(values.next());
console.dir(values.next());

Run

Results:

Spec

home license contribute feedback toggle light/dark mode