Map : Object

Maps allow associating keys and values similar to normal %%/Object|Objects%%
except Maps allow any Object to be used as a key instead of just
%%/String|Strings%% and %%/Symbol|Symbols%%.  

Maps use %%#get|get()%% and %%#set|set()%% methods to access the values stored in the Map.

A Map are often called a HashTable or a Dictionary in other languages.

Iterable:
true

Version:
ECMAScript 2015

Spec:
http://www.ecma-international.org/ecma-262/6.0/#sec-map-objects

----
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));
</example>

Spec:
http://www.ecma-international.org/ecma-262/6.0/#sec-map-iterable

----
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));
</example>

Spec:
http://www.ecma-international.org/ecma-262/6.0/#sec-map-iterable

----
instance.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);
</example>

Spec:
http://www.ecma-international.org/ecma-262/6.0/#sec-get-map.prototype.size

----
prototype.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);
</example>

Spec:
http://www.ecma-international.org/ecma-262/6.0/#sec-map.prototype.clear

----
prototype.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);
</example>

Spec:
http://www.ecma-international.org/ecma-262/6.0/#sec-map.prototype.delete

----
prototype.entries() : Iterator<Array>

Returns an iterator of the index and items in **this** where the 
%%Iterator#next|**values**s%% of the iterator are of the form
**[key : %%/Object|Object%%, value : %%/Object|Object%%]**.

The **entries** function is also returned for 
**this[%%/Symbol#iterator|Symbol.iterator%%]** so you can 
iterate over **this** directly to get the entries.

See also %%#keys|**keys()**%% and %%#values|**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());
</example>

Spec:
http://www.ecma-international.org/ecma-262/6.0/#sec-map.prototype.entries

----
prototype.forEach(callback(value : Object, key : Object, map : Map) : undefined, [thisArg : Object]) : 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 + '"');
});
</example>

Spec:
http://www.ecma-international.org/ecma-262/6.0/#sec-map.prototype.forEach

----
prototype.get(key : Object) : Object

Returns the value stored for **key**. If no value is stored,
returns %%/undefined|**undefined**%%.
See also %%#has|**has()**%% and %%#set|**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']);
</example>

Spec:
http://www.ecma-international.org/ecma-262/6.0/#sec-map.prototype.get

----
prototype.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'));
</example>

Spec:
http://www.ecma-international.org/ecma-262/6.0/#sec-map.prototype.has

----
prototype.keys() : Iterator

Returns an iterator of the keys in **this**.
See also %%#entries|**entries()**%% and %%#values|**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());
</example>

Spec:
http://www.ecma-international.org/ecma-262/6.0/#sec-map.prototype.keys

----
prototype.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|**get()**%% and %%#has|**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'));
</example>

Spec:
http://www.ecma-international.org/ecma-262/6.0/#sec-map.prototype.set

----
prototype.values() : Iterator

Returns an iterator of the values in **this**.
See also %%#entries|**entries()**%% and %%#keys|**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());
</example>

Spec:
http://www.ecma-international.org/ecma-262/6.0/#sec-map.prototype.values