Map

  • Revision slug: JavaScript/Reference/Global_Objects/Map
  • Revision title: Map
  • Revision id: 343331
  • Created:
  • Creator: ziyunfei
  • Is current revision? No
  • Comment

Revision Content

{{ SeeCompatTable() }}

{{ 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. Any value (both objects and primitive values) may be used as either a key or a value.

Key equality is based on the "same-value" algorithm: NaN is considered the same as NaN (even though NaN !== NaN), -0 and +0 are considered distinct (even though -0 === +0), and all other values are considered equal according to the semantics of the === operator.

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.
myMap.clear() {{ fx_minversion_inline("19") }} Removes all key/value pairs from myMap.
Property Description
myMap.size

Returns the number of key/value pairs in myMap.

{{ fx_minversion_inline("19") }}In Firefox 18 and earlier, size was a method. In Firefox 19 and later it is a property.

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

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

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"

Objects and maps compared

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, Objects have been used as Maps historically; however, there are important differences between Objects and Maps that make using a Map better.

  • An Object has a prototype, so there are default keys in the map. However, this can be bypassed using map = Object.create(null).
  • The keys of an Object are Strings, where they can be any value for a Map.
  • You can get the size of a Map easily while you have to manually keep track of size for an Object.

Use maps over objects when keys are unknown until run time, and when all keys are the same type and all values are the same type.

Use objects when there is logic that operates on individual elements.

Browser compatibility

{{ CompatibilityTable() }}

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support {{ CompatNo() }} {{ CompatGeckoDesktop("13") }} {{ CompatNo() }} {{ CompatNo() }} {{ CompatNo() }}
iterable {{ CompatNo() }} {{ CompatGeckoDesktop("17") }} {{ CompatNo() }} {{ CompatNo() }} {{ CompatNo() }}
Map.clear() {{ CompatNo() }} {{CompatGeckoDesktop("19")}} {{ CompatNo() }} {{ CompatNo() }} {{ CompatNo() }}
Feature Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support {{ CompatNo() }} {{ CompatGeckoMobile("13") }} {{ CompatNo() }} {{ CompatNo() }} {{ CompatNo() }}
iterable {{ CompatNo() }} {{ CompatGeckoDesktop("17") }} {{ CompatNo() }} {{ CompatNo() }} {{ CompatNo() }}
Map.clear() {{ CompatNo() }} {{CompatGeckoMobile("19")}} {{ CompatNo() }} {{ CompatNo() }} {{ CompatNo() }}

See also

Revision Source

<p>{{ SeeCompatTable() }}</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 id="Introduction">Introduction</h2>
<p><code>Map</code> objects are simple key/value maps. Any value (both objects and primitive values) may be used as either a key or a value.</p>
<p>Key equality is based on the "same-value" algorithm: <code>NaN</code> is considered the same as <code>NaN</code> (even though <code>NaN !== NaN</code>), <code>-0</code> and <code>+0</code> are considered distinct (even though <code>-0 === +0</code>), and all other values are considered equal according to the semantics of the === operator.</p>
<h2 id="API">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>
    <tr>
      <td><code>myMap.clear()</code></td>
      <td>{{ fx_minversion_inline("19") }} Removes all key/value pairs from <code>myMap</code>.</td>
    </tr>
    <tr>
      <th>Property</th>
      <th>Description</th>
    </tr>
    <tr>
      <td><code>myMap.size</code></td>
      <td>
        <p>Returns the number of key/value pairs in <code>myMap</code>.</p>
        {{ fx_minversion_inline("19") }}In Firefox 18 and earlier, <code>size</code> was a method.  In Firefox 19 and later it is a property.</td>
    </tr>
  </tbody>
</table>
<h2 id="Examples">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");

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 () {}
</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 id="Objects_and_maps_compared">Objects and maps compared</h2>
<p><a href="/en/JavaScript/Reference/Global_Objects/Object" title="en/JavaScript/Reference/Global_Objects/Object"><code>Object</code></a>s are similar to <code>Map</code>s 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, <code>Object</code>s have been used as <code>Map</code>s historically; however, there are important differences between <code>Object</code>s and <code>Map</code>s that make using a <code>Map</code> better.</p>
<ul>
  <li>An <code>Object</code> has a prototype, so there are default keys in the map. However, this can be bypassed using <code>map = Object.create(null)</code>.</li>
  <li>The keys of an <code>Object</code> are <a href="/en/JavaScript/Reference/Global_Objects/String" title="en/JavaScript/Reference/Global_Objects/String">String</a>s, where they can be any value for a <code>Map</code>.</li>
  <li>You can get the size of a <code>Map</code> easily while you have to manually keep track of size for an <code>Object</code>.</li>
</ul>
<p>Use maps over objects when keys are unknown until run time, and when all keys are the same type and all values are the same type.</p>
<p>Use objects when there is logic that operates on individual elements.</p>
<h2 id="Browser_compatibility">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>
      <tr>
        <td>iterable</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatGeckoDesktop("17") }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
      </tr>
      <tr>
        <td>Map.clear()</td>
        <td>{{ CompatNo() }}</td>
        <td>{{CompatGeckoDesktop("19")}}</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>{{ CompatGeckoMobile("13") }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
      </tr>
      <tr>
        <td>iterable</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatGeckoDesktop("17") }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
      </tr>
      <tr>
        <td>Map.clear()</td>
        <td>{{ CompatNo() }}</td>
        <td>{{CompatGeckoMobile("19")}}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
      </tr>
    </tbody>
  </table>
</div>
<h2 id="See_also">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>
Revert to this revision