24.1 Map Objects

Map objects are collections of key/value pairs where both the keys and values may be arbitrary ECMAScript language values. A distinct key value may only occur in one key/value pair within the Map's collection. Distinct key values are discriminated using the SameValueZero comparison algorithm.

Map object must be implemented using either hash tables or other mechanisms that, on average, provide access times that are sublinear on the number of elements in the collection. The data structures used in this Map objects specification is only intended to describe the required observable semantics of Map objects. It is not intended to be a viable implementation model.

24.1.1 The Map Constructor

The Map constructor:

  • is %Map%.
  • is the initial value of the "Map" property of the global object.
  • creates and initializes a new Map object when called as a constructor.
  • is not intended to be called as a function and will throw an exception when called in that manner.
  • is designed to be subclassable. It may be used as the value in an extends clause of a class definition. Subclass constructors that intend to inherit the specified Map behaviour must include a super call to the Map constructor to create and initialize the subclass instance with the internal state necessary to support the Map.prototype built-in methods.

24.1.1.1 Map ( [ iterable ] )

When the Map function is called with optional argument iterable, the following steps are taken:

  1. If NewTarget is undefined, throw a TypeError exception.
  2. Let map be ? OrdinaryCreateFromConstructor(NewTarget, "%Map.prototype%", « [[MapData]] »).
  3. Set map.[[MapData]] to a new empty List.
  4. If iterable is either undefined or null, return map.
  5. Let adder be ? Get(map, "set").
  6. Return ? AddEntriesFromIterable(map, iterable, adder).
Note

If the parameter iterable is present, it is expected to be an object that implements an @@iterator method that returns an iterator object that produces a two element array-like object whose first element is a value that will be used as a Map key and whose second element is the value to associate with that key.

24.1.1.2 AddEntriesFromIterable ( target, iterable, adder )

The abstract operation AddEntriesFromIterable takes arguments target, iterable, and adder (a function object). adder will be invoked, with target as the receiver. It performs the following steps when called:

  1. If IsCallable(adder) is false, throw a TypeError exception.
  2. Assert: iterable is present, and is neither undefined nor null.
  3. Let iteratorRecord be ? GetIterator(iterable).
  4. Repeat,
    1. Let next be ? IteratorStep(iteratorRecord).
    2. If next is false, return target.
    3. Let nextItem be ? IteratorValue(next).
    4. If Type(nextItem) is not Object, then
      1. Let error be ThrowCompletion(a newly created TypeError object).
      2. Return ? IteratorClose(iteratorRecord, error).
    5. Let k be Get(nextItem, "0").
    6. If k is an abrupt completion, return ? IteratorClose(iteratorRecord, k).
    7. Let v be Get(nextItem, "1").
    8. If v is an abrupt completion, return ? IteratorClose(iteratorRecord, v).
    9. Let status be Call(adder, target, « k.[[Value]], v.[[Value]] »).
    10. If status is an abrupt completion, return ? IteratorClose(iteratorRecord, status).
Note

The parameter iterable is expected to be an object that implements an @@iterator method that returns an iterator object that produces a two element array-like object whose first element is a value that will be used as a Map key and whose second element is the value to associate with that key.

24.1.2 Properties of the Map Constructor

The Map constructor:

  • has a [[Prototype]] internal slot whose value is %Function.prototype%.
  • has the following properties:

24.1.2.1 Map.prototype

The initial value of Map.prototype is the Map prototype object.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

24.1.2.2 get Map [ @@species ]

Map[@@species] is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Return the this value.

The value of the "name" property of this function is "get [Symbol.species]".

Note

Methods that create derived collection objects should call @@species to determine the constructor to use to create the derived objects. Subclass constructor may over-ride @@species to change the default constructor assignment.

24.1.3 Properties of the Map Prototype Object

The Map prototype object:

24.1.3.1 Map.prototype.clear ( )

The following steps are taken:

  1. Let M be the this value.
  2. Perform ? RequireInternalSlot(M, [[MapData]]).
  3. Let entries be the List that is M.[[MapData]].
  4. For each Record { [[Key]], [[Value]] } p of entries, do
    1. Set p.[[Key]] to empty.
    2. Set p.[[Value]] to empty.
  5. Return undefined.
Note

The existing [[MapData]] List is preserved because there may be existing Map Iterator objects that are suspended midway through iterating over that List.

24.1.3.2 Map.prototype.constructor

The initial value of Map.prototype.constructor is %Map%.

24.1.3.3 Map.prototype.delete ( key )

The following steps are taken:

  1. Let M be the this value.
  2. Perform ? RequireInternalSlot(M, [[MapData]]).
  3. Let entries be the List that is M.[[MapData]].
  4. For each Record { [[Key]], [[Value]] } p of entries, do
    1. If p.[[Key]] is not empty and SameValueZero(p.[[Key]], key) is true, then
      1. Set p.[[Key]] to empty.
      2. Set p.[[Value]] to empty.
      3. Return true.
  5. Return false.
Note

The value empty is used as a specification device to indicate that an entry has been deleted. Actual implementations may take other actions such as physically removing the entry from internal data structures.

24.1.3.4 Map.prototype.entries ( )

The following steps are taken:

  1. Let M be the this value.
  2. Return ? CreateMapIterator(M, key+value).

24.1.3.5 Map.prototype.forEach ( callbackfn [ , thisArg ] )

When the forEach method is called with one or two arguments, the following steps are taken:

  1. Let M be the this value.
  2. Perform ? RequireInternalSlot(M, [[MapData]]).
  3. If IsCallable(callbackfn) is false, throw a TypeError exception.
  4. Let entries be the List that is M.[[MapData]].
  5. For each Record { [[Key]], [[Value]] } e of entries, do
    1. If e.[[Key]] is not empty, then
      1. Perform ? Call(callbackfn, thisArg, « e.[[Value]], e.[[Key]], M »).
  6. Return undefined.
Note

callbackfn should be a function that accepts three arguments. forEach calls callbackfn once for each key/value pair present in the map object, in key insertion order. callbackfn is called only for keys of the map which actually exist; it is not called for keys that have been deleted from the map.

If a thisArg parameter is provided, it will be used as the this value for each invocation of callbackfn. If it is not provided, undefined is used instead.

callbackfn is called with three arguments: the value of the item, the key of the item, and the Map object being traversed.

forEach does not directly mutate the object on which it is called but the object may be mutated by the calls to callbackfn. Each entry of a map's [[MapData]] is only visited once. New keys added after the call to forEach begins are visited. A key will be revisited if it is deleted after it has been visited and then re-added before the forEach call completes. Keys that are deleted after the call to forEach begins and before being visited are not visited unless the key is added again before the forEach call completes.

24.1.3.6 Map.prototype.get ( key )

The following steps are taken:

  1. Let M be the this value.
  2. Perform ? RequireInternalSlot(M, [[MapData]]).
  3. Let entries be the List that is M.[[MapData]].
  4. For each Record { [[Key]], [[Value]] } p of entries, do
    1. If p.[[Key]] is not empty and SameValueZero(p.[[Key]], key) is true, return p.[[Value]].
  5. Return undefined.

24.1.3.7 Map.prototype.has ( key )

The following steps are taken:

  1. Let M be the this value.
  2. Perform ? RequireInternalSlot(M, [[MapData]]).
  3. Let entries be the List that is M.[[MapData]].
  4. For each Record { [[Key]], [[Value]] } p of entries, do
    1. If p.[[Key]] is not empty and SameValueZero(p.[[Key]], key) is true, return true.
  5. Return false.

24.1.3.8 Map.prototype.keys ( )

The following steps are taken:

  1. Let M be the this value.
  2. Return ? CreateMapIterator(M, key).

24.1.3.9 Map.prototype.set ( key, value )

The following steps are taken:

  1. Let M be the this value.
  2. Perform ? RequireInternalSlot(M, [[MapData]]).
  3. Let entries be the List that is M.[[MapData]].
  4. For each Record { [[Key]], [[Value]] } p of entries, do
    1. If p.[[Key]] is not empty and SameValueZero(p.[[Key]], key) is true, then
      1. Set p.[[Value]] to value.
      2. Return M.
  5. If key is -0𝔽, set key to +0𝔽.
  6. Let p be the Record { [[Key]]: key, [[Value]]: value }.
  7. Append p as the last element of entries.
  8. Return M.

24.1.3.10 get Map.prototype.size

Map.prototype.size is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let M be the this value.
  2. Perform ? RequireInternalSlot(M, [[MapData]]).
  3. Let entries be the List that is M.[[MapData]].
  4. Let count be 0.
  5. For each Record { [[Key]], [[Value]] } p of entries, do
    1. If p.[[Key]] is not empty, set count to count + 1.
  6. Return 𝔽(count).

24.1.3.11 Map.prototype.values ( )

The following steps are taken:

  1. Let M be the this value.
  2. Return ? CreateMapIterator(M, value).

24.1.3.12 Map.prototype [ @@iterator ] ( )

The initial value of the @@iterator property is the same function object as the initial value of the "entries" property.

24.1.3.13 Map.prototype [ @@toStringTag ]

The initial value of the @@toStringTag property is the String value "Map".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

24.1.4 Properties of Map Instances

Map instances are ordinary objects that inherit properties from the Map prototype. Map instances also have a [[MapData]] internal slot.

24.1.5 Map Iterator Objects

A Map Iterator is an object, that represents a specific iteration over some specific Map instance object. There is not a named constructor for Map Iterator objects. Instead, map iterator objects are created by calling certain methods of Map instance objects.

24.1.5.1 CreateMapIterator ( map, kind )

The abstract operation CreateMapIterator takes arguments map and kind. This operation is used to create iterator objects for Map methods that return such iterators. It performs the following steps when called:

  1. Assert: kind is key+value, key, or value.
  2. Perform ? RequireInternalSlot(map, [[MapData]]).
  3. Let closure be a new Abstract Closure with no parameters that captures map and kind and performs the following steps when called:
    1. Let entries be the List that is map.[[MapData]].
    2. Let index be 0.
    3. Let numEntries be the number of elements of entries.
    4. Repeat, while index < numEntries,
      1. Let e be the Record { [[Key]], [[Value]] } that is the value of entries[index].
      2. Set index to index + 1.
      3. If e.[[Key]] is not empty, then
        1. If kind is key, let result be e.[[Key]].
        2. Else if kind is value, let result be e.[[Value]].
        3. Else,
          1. Assert: kind is key+value.
          2. Let result be ! CreateArrayFromListe.[[Key]], e.[[Value]] »).
        4. Perform ? Yield(result).
        5. NOTE: the number of elements in entries may have changed while execution of this abstract operation was paused by Yield.
        6. Set numEntries to the number of elements of entries.
    5. Return undefined.
  4. Return ! CreateIteratorFromClosure(closure, "%MapIteratorPrototype%", %MapIteratorPrototype%).

24.1.5.2 The %MapIteratorPrototype% Object

The %MapIteratorPrototype% object:

  • has properties that are inherited by all Map Iterator Objects.
  • is an ordinary object.
  • has a [[Prototype]] internal slot whose value is %IteratorPrototype%.
  • has the following properties:

24.1.5.2.1 %MapIteratorPrototype%.next ( )

  1. Return ? GeneratorResume(this value, empty, "%MapIteratorPrototype%").

24.1.5.2.2 %MapIteratorPrototype% [ @@toStringTag ]

The initial value of the @@toStringTag property is the String value "Map Iterator".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.