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.
The Map constructor is the %Map% intrinsic object and the initial value of the Map
property of the global
object. When called as a constructor it creates and initializes a new Map object. Map
is not intended to be
called as a function and will throw an exception when called in that manner.
The Map
constructor 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.
When the Map
function is called with optional argument the following steps are
taken:
"%MapPrototype%"
, «[[MapData]]» )."set"
)."0"
)."1"
).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.
The value of the [[Prototype]] internal slot of the Map constructor is the intrinsic object %FunctionPrototype% (19.2.3).
Besides the length
property (whose value is 0), the Map constructor has the following
properties:
The initial value of Map.prototype
is the intrinsic object %MapPrototype% (23.1.3).
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.
Map[@@species]
is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:
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.
The Map prototype object is the intrinsic object %MapPrototype%. The value of the [[Prototype]] internal slot of the Map prototype object is the intrinsic object %ObjectPrototype% (19.1.3). The Map prototype object is an ordinary object. It does not have a [[MapData]] internal slot.
The following steps are taken:
The initial value of Map.prototype.constructor
is the intrinsic object %Map%.
The following steps are taken:
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.
The following steps are taken:
"key+value"
).When the forEach
method is called with one or two arguments, the following steps are
taken:
The length
property of the forEach
method is 1.
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.
The following steps are taken:
The following steps are taken:
The following steps are taken:
"key"
).The following steps are taken:
Map.prototype.size is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:
The following steps are taken:
"value"
).The initial value of the @@iterator property is the same function object as the initial value of the entries property.
The initial value of the @@toStringTag property is the String value "Map"
.
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.
Map instances are ordinary objects that inherit properties from the Map prototype. Map instances also have a [[MapData]] internal slot.
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.
Several methods of Map objects return Iterator objects. The abstract operation CreateMapIterator with arguments map and kind is used to create such iterator objects. It performs the following steps:
All Map Iterator Objects inherit properties from the %MapIteratorPrototype% intrinsic object. The %MapIteratorPrototype% intrinsic object is an ordinary object and its [[Prototype]] internal slot is the %IteratorPrototype% intrinsic object (25.1.2). In addition, %MapIteratorPrototype% has the following properties:
key
", let result be e.[[key]].value
", let result be e.[[value]]."key+value"
.The initial value of the @@toStringTag property is the String value "Map Iterator"
.
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.
Map Iterator instances are ordinary objects that inherit properties from the %MapIteratorPrototype% intrinsic object. Map Iterator instances are initially created with the internal slots described in Table 50.
Internal Slot | Description |
---|---|
[[Map]] | The Map object that is being iterated. |
[[MapNextIndex]] | The integer index of the next Map data element to be examined by this iterator. |
[[MapIterationKind]] | A String value that identifies what is to be returned for each element of the iteration. The possible values are: "key" , "value" , "key+value" . |
Set objects are collections of ECMAScript language values. A distinct value may only occur once as an element of a Set's collection. Distinct values are discriminated using the SameValueZero comparison algorithm.
Set objects 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 Set objects specification is only intended to describe the required observable semantics of Set objects. It is not intended to be a viable implementation model.
The Set constructor is the %Set% intrinsic object and the initial value of the Set
property of the global
object. When called as a constructor it creates and initializes a new Set object. Set
is not intended to be
called as a function and will throw an exception when called in that manner.
The Set
constructor 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 Set
behaviour must
include a super
call to the Set
constructor to create and initialize the subclass instance with
the internal state necessary to support the Set.prototype
built-in methods.
When the Set
function is called with optional argument iterable the
following steps are taken:
"%SetPrototype%"
, «[[SetData]]» )."add"
).The value of the [[Prototype]] internal slot of the Set constructor is the intrinsic object %FunctionPrototype% (19.2.3).
Besides the length
property (whose value is 0), the Set constructor has the following
properties:
The initial value of Set.prototype
is the intrinsic %SetPrototype% object (23.2.3).
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.
Set[@@species]
is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:
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.
The Set prototype object is the intrinsic object %SetPrototype%. The value of the [[Prototype]] internal slot of the Set prototype object is the intrinsic object %ObjectPrototype% (19.1.3). The Set prototype object is an ordinary object. It does not have a [[SetData]] internal slot.
The following steps are taken:
The following steps are taken:
The initial value of Set.prototype.constructor
is the intrinsic object %Set%.
The following steps are taken:
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.
The following steps are taken:
key+value
").NOTE For iteration purposes, a Set appears similar to a Map where each entry has the same value for its key and value.
When the forEach
method is called with one or two arguments, the following steps are
taken:
The length
property of the forEach
method is 1.
NOTE callbackfn should be a function that accepts three arguments.
forEach
calls callbackfn once for each value present in the set object, in value insertion
order. callbackfn is called only for values of the Set which actually exist; it is not called for keys that
have been deleted from the set.
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 first two arguments are a value contained in the Set. The same value is passed for both arguments. The Set object being traversed is passed as the third argument.
The callbackfn is called with three arguments to be consistent with the call back functions used by
forEach
methods for Map and Array. For Sets, each item value is considered to be both the key and the
value.
forEach
does not directly mutate the object on which it is called but the object may be mutated by the
calls to callbackfn.
Each value is normally visited only once. However, a value will be revisited if it is deleted after it has been
visited and then re-added before the forEach
call completes. Values that are deleted after the call to
forEach
begins and before being visited are not visited unless the value is added again before the
forEach
call completes. New values added after the call to forEach
begins are visited.
The following steps are taken:
The initial value of the keys
property is the same function object as the initial value of the
values
property.
NOTE For iteration purposes, a Set appears similar to a Map where each entry has the same value for its key and value.
Set.prototype.size
is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:
The following steps are taken:
value
").The initial value of the @@iterator property is the same function object as the initial value of the
values
property.
The initial value of the @@toStringTag property is the String value "Set"
.
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.
Set instances are ordinary objects that inherit properties from the Set prototype. Set instances also have a [[SetData]] internal slot.
A Set Iterator is an ordinary object, with the structure defined below, that represents a specific iteration over some specific Set instance object. There is not a named constructor for Set Iterator objects. Instead, set iterator objects are created by calling certain methods of Set instance objects.
Several methods of Set objects return Iterator objects. The abstract operation CreateSetIterator with arguments set and kind is used to create such iterator objects. It performs the following steps:
All Set Iterator Objects inherit properties from the %SetIteratorPrototype% intrinsic object. The %SetIteratorPrototype% intrinsic object is an ordinary object and its [[Prototype]] internal slot is the %IteratorPrototype% intrinsic object (25.1.2). In addition, %SetIteratorPrototype% has the following properties:
key+value
", then
The initial value of the @@toStringTag property is the String value "Set Iterator"
.
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.
Set Iterator instances are ordinary objects that inherit properties from the %SetIteratorPrototype% intrinsic object. Set Iterator instances are initially created with the internal slots specified in Table 51.
Internal Slot | Description |
---|---|
[[IteratedSet]] | The Set object that is being iterated. |
[[SetNextIndex]] | The integer index of the next Set data element to be examined by this iterator |
[[SetIterationKind]] | A Sring value that identifies what is to be returned for each element of the iteration. The possible values are: "key" , "value" , "key+value" . "key" and "value" have the same meaning. |
WeakMap objects are collections of key/value pairs where the keys are objects and values may be arbitrary ECMAScript language values. A WeakMap may be queried to see if it contains a key/value pair with a specific key, but no mechanism is provided for enumerating the objects it holds as keys. If an object that is being used as the key of a WeakMap key/value pair is only reachable by following a chain of references that start within that WeakMap, then that key/value pair is inaccessible and is automatically removed from the WeakMap. WeakMap implementations must detect and remove such key/value pairs and any associated resources.
An implementation may impose an arbitrarily determined latency between the time a key/value pair of a WeakMap becomes inaccessible and the time when the key/value pair is removed from the WeakMap. If this latency was observable to ECMAScript program, it would be a source of indeterminacy that could impact program execution. For that reason, an ECMAScript implementation must not provide any means to observe a key of a WeakMap that does not require the observer to present the observed key.
WeakMap objects must be implemented using either hash tables or other mechanisms that, on average, provide access times that are sublinear on the number of key/value pairs in the collection. The data structure used in this WeakMap objects specification are only intended to describe the required observable semantics of WeakMap objects. It is not intended to be a viable implementation model.
NOTE WeakMap and WeakSets are intended to provide mechanisms for dynamically associating state with an object in a manner that does not “leak” memory resources if, in the absence of the WeakMap or WeakSet, the object otherwise became inaccessible and subject to resource reclamation by the implementation's garbage collection mechanisms. Achieving this characteristic can be achieved by using an inverted per-object mapping of weak map instances to keys. Alternatively each weak map may internally store its key to value mappings but this approach requires coordination between the WeakMap or WeakSet implementation and the garbage collector. The following references describe mechanism that may be useful to implementations of WeakMap and WeakSets:
Barry Hayes. 1997. Ephemerons: a new finalization mechanism. In Proceedings of the 12th ACM SIGPLAN conference on Object-oriented programming, systems, languages, and applications (OOPSLA '97), A. Michael Berman (Ed.). ACM, New York, NY, USA, 176-183, http://doi.acm.org/10.1145/263698.263733.
Alexandra Barros, Roberto Ierusalimschy, Eliminating Cycles in Weak Tables. Journal of Universal Computer Science - J.UCS , vol. 14, no. 21, pp. 3481-3497, 2008, http://www.jucs.org/jucs_14_21/eliminating_cycles_in_weak
The WeakMap constructor is the %WeakMap% intrinsic object and the initial value of the WeakMap
property of
the global object. When called as a constructor it creates and initializes a new WeakMap object. WeakMap
is
not intended to be called as a function and will throw an exception when called in that manner.
The WeakMap
constructor 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
WeakMap
behaviour must include a super
call to the WeakMap
constructor to create
and initialize the subclass instance with the internal state necessary to support the WeakMap.prototype
built-in methods.
When the WeakMap
function is called with optional argument iterable the
following steps are taken:
"%WeakMapPrototype%"
, «[[WeakMapData]]» )."set"
)."0"
)."1"
).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 WeakMap key and whose second element is the value to associate with that key.
The value of the [[Prototype]] internal slot of the WeakMap constructor is the intrinsic object %FunctionPrototype% (19.2.3).
Besides the length
property (whose value is 0), the WeakMap constructor has the following
properties:
The initial value of WeakMap.prototype
is the intrinsic object %WeakMapPrototype% (23.3.3).
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.
The WeakMap prototype object is the intrinsic object %WeakMapPrototype%. The value of the [[Prototype]] internal slot of the WeakMap prototype object is the intrinsic object %ObjectPrototype% (19.1.3). The WeakMap prototype object is an ordinary object. It does not have a [[WeakMapData]] internal slot.
The initial value of WeakMap.prototype.constructor
is the intrinsic object %WeakMap%.
The following steps are taken:
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.
The following steps are taken:
The following steps are taken:
The following steps are taken:
The initial value of the @@toStringTag property is the String value "WeakMap"
.
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.
WeakMap instances are ordinary objects that inherit properties from the WeakMap prototype. WeakMap instances also have a [[WeakMapData]] internal slot.
WeakSet objects are collections of objects. A distinct object may only occur once as an element of a WeakSet’s collection. A WeakSet may be queried to see if it contains a specific object, but no mechanism is provided for enumerating the objects it holds. If an object that is contained by a WeakSet is only reachable by following a chain of references that start within that WeakSet, then that object is inaccessible and is automatically removed from the WeakSet. WeakSet implementations must detect and remove such objects and any associated resources.
An implementation may impose an arbitrarily determined latency between the time an object contained in a WeakSet becomes inaccessible and the time when the object is removed from the WeakSet. If this latency was observable to ECMAScript program, it would be a source of indeterminacy that could impact program execution. For that reason, an ECMAScript implementation must not provide any means to determine if a WeakSet contains a particular object that does not require the observer to present the observed object.
WeakSet objects 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 structure used in this WeakSet objects specification is only intended to describe the required observable semantics of WeakSet objects. It is not intended to be a viable implementation model.
NOTE See the NOTE in 23.3.
The WeakSet constructor is the %WeakSet% intrinsic object and the initial value of the WeakSet
property of
the global object. When called as a constructor it creates and initializes a new WeakSet object. WeakSet
is
not intended to be called as a function and will throw an exception when called in that manner.
The WeakSet
constructor 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
WeakSet
behaviour must include a super
call to the WeakSet
constructor to create
and initialize the subclass instance with the internal state necessary to support the WeakSet.prototype
built-in methods.
When the WeakSet
function is called with optional argument iterable the
following steps are taken:
"%WeakSetPrototype%"
, «[[WeakSetData]]» )."add"
).The value of the [[Prototype]] internal slot of the WeakSet constructor is the intrinsic object %FunctionPrototype% (19.2.3).
Besides the length
property (whose value is 0), the WeakSet constructor has the following
properties:
The initial value of WeakSet.prototype
is the intrinsic %WeakSetPrototype% object (23.4.3).
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.
The WeakSet prototype object is the intrinsic object %WeakSetPrototype%. The value of the [[Prototype]] internal slot of the WeakSet prototype object is the intrinsic object %ObjectPrototype% (19.1.3). The WeakSet prototype object is an ordinary object. It does not have a [[WeakSetData]] internal slot.
The following steps are taken:
The initial value of WeakSet.prototype.constructor
is the %WeakSet% intrinsic object.
The following steps are taken:
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.
The following steps are taken:
The initial value of the @@toStringTag property is the String value "WeakSet"
.
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.
WeakSet instances are ordinary objects that inherit properties from the WeakSet prototype. WeakSet instances also have a [[WeakSetData]] internal slot.