Map

  • Revision slug: JavaScript/Reference/Global_Objects/Map
  • Revision title: Map
  • Revision id: 19295
  • Created:
  • Creator: Dmandelin
  • Is current revision? No
  • Comment 2 words added, 2 words removed

Revision Content

{{ fx_minversion_header("13") }}

{{ Non-standard_header() }}

{{ warning("The SpiderMonkey Map implementation is a prototype and the Map API and semantics specifications are unstable. The SpiderMonkey implementation may not reflect the latest specification draft. It is subject to change anytime. It is provided as an experimental feature. Do not rely on it for production code.") }}

Introduction

Map objects are simple key/value maps. Keys can be primitive values or object references. Keys equality is not based on the same algorithm than the one used in the === operator. Specifically, for Maps, +0 (which is strictly equal to -0) and -0 are different keys. NaN can also be associated a value, too.

API

Method Description
myMap.get(key) Returns the value associated to the key, or undefined if there is none.
myMap.set(key, value) Sets the value for the key  in myMap. Returns undefined.
myMap.has(key) Returns a boolean asserting whether a value has been associated to the key in myMap or not
myMap.delete(key) Removes any value associated to the key. After such a call, myMap.has(key) will return false.

It is expected that the final version of ECMAScript 6 will allow for iterating over maps and enumerating their keys. As these features are currently not specified, they are not supported in SpiderMonkey.

Examples

var myMap = new Map();

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

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

// 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 () {}

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"

Also note that JavaScript has two zero values, +0 and -0. These two zero values are treated as different keys in Maps:

var myMap = new Map();
myMap.set(0, "positive zero");
myMap.set(-0, "negative zero");

0 === -0; // true

myMap.get(-0); // "negative zero"
myMap.get(0);  // "positive zero"

Browser compatibility

{{ CompatibilityTable() }}

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support {{ CompatNo() }} {{ CompatGeckoDesktop("13") }} {{ CompatNo() }} {{ CompatNo() }} {{ CompatNo() }}
Feature Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support {{ CompatNo() }} {{ CompatGeckoDesktop("13") }} {{ CompatNo() }} {{ CompatNo() }} {{ CompatNo() }}

See also

{{ languages( { "zh-cn": "zh-cn/JavaScript/Reference/Global_Objects/Map"} ) }}

Revision Source

<p>{{ fx_minversion_header("13") }}</p>
<p>{{ Non-standard_header() }}</p>
<p>{{ warning("The SpiderMonkey Map implementation is a prototype and the Map API and semantics specifications are unstable. The SpiderMonkey implementation may not reflect the latest specification draft. It is subject to change anytime. It is provided as an experimental feature. Do not rely on it for production code.") }}</p>
<h2>Introduction</h2>
<p><code>Map</code> objects are simple key/value maps. Keys can be primitive values or object references. Keys equality is not based on the same algorithm than the one used in the === operator. Specifically, for Maps, <code>+0</code> (which is strictly equal to <code>-0</code>) and <code>-0</code> are different keys. <code>NaN</code> can also be associated a value, too.</p>
<h2>API</h2>
<table class="standard-table"> <tbody> <tr> <th>Method</th> <th>Description</th> </tr> <tr> <td><code>myMap.get(key)</code></td> <td>Returns the value associated to the <code>key</code>, or <code>undefined</code> if there is none.</td> </tr> <tr> <td><code>myMap.set(key, value)</code></td> <td>Sets the value for the <code>key</code>  in <code>myMap</code>. Returns <code>undefined</code>.</td> </tr> <tr> <td><code>myMap.has(key)</code></td> <td>Returns a boolean asserting whether a value has been associated to the <code>key</code> in <code>myMap</code> or not</td> </tr> <tr> <td><code>myMap.delete(key)</code></td> <td>Removes any value associated to the <code>key</code>. After such a call, <code>myMap.has(key)</code> will return <code>false</code>.</td> </tr> </tbody>
</table>
<p>It is expected that the final version of ECMAScript 6 will allow for iterating over maps and enumerating their keys. As these features are currently not specified, they are not supported in SpiderMonkey.</p>
<h2>Examples</h2>
<pre class="brush: js">var myMap = new Map();

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

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

// 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 () {}
</pre>
<p><code>NaN</code> can also be used as a key. Even though every <code>NaN</code> is not equal to itself (<code>NaN !== NaN</code> is true), the following example works, because <code>NaN</code>s are indistinguishable from each other:</p>
<pre class="brush: js">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"
</pre>
<p>Also note that JavaScript has two zero values, +0 and -0. These two zero values are treated as different keys in <code>Map</code>s:</p>
<pre class="brush: js">var myMap = new Map();
myMap.set(0, "positive zero");
myMap.set(-0, "negative zero");

0 === -0; // true

myMap.get(-0); // "negative zero"
myMap.get(0);  // "positive zero"
</pre>
<h2>Browser compatibility</h2>
<p>{{ CompatibilityTable() }}</p>
<div id="compat-desktop"> <table class="compat-table"> <tbody> <tr> <th>Feature</th> <th>Chrome</th> <th>Firefox (Gecko)</th> <th>Internet Explorer</th> <th>Opera</th> <th>Safari</th> </tr> <tr> <td>Basic support</td> <td>{{ CompatNo() }}</td> <td>{{ CompatGeckoDesktop("13") }}</td> <td>{{ CompatNo() }}</td> <td>{{ CompatNo() }}</td> <td>{{ CompatNo() }}</td> </tr> </tbody> </table>
</div>
<div id="compat-mobile"> <table class="compat-table"> <tbody> <tr> <th>Feature</th> <th>Android</th> <th>Firefox Mobile (Gecko)</th> <th>IE Mobile</th> <th>Opera Mobile</th> <th>Safari Mobile</th> </tr> <tr> <td>Basic support</td> <td>{{ CompatNo() }}</td> <td>{{ CompatGeckoDesktop("13") }}</td> <td>{{ CompatNo() }}</td> <td>{{ CompatNo() }}</td> <td>{{ CompatNo() }}</td> </tr> </tbody> </table>
</div>
<h2>See also</h2>
<ul> <li><a class="link-https" href="https://bugzilla.mozilla.org/show_bug.cgi?id=697479">Map and Set bug at Mozilla</a></li> <li><a class="external" href="http://wiki.ecmascript.org/doku.php?id=harmony:simple_maps_and_sets">ECMAScript Harmony proposal</a></li>
</ul>
<p>{{ languages( { "zh-cn": "zh-cn/JavaScript/Reference/Global_Objects/Map"} ) }}</p>
Revert to this revision