24.2 Set Objects
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
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.
24.2.1 The Set Constructor
The Set
- is %Set%.
- is the initial value of the
"Set" property of theglobal object . - creates and initializes a new Set 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 Set behaviour must include asuper
call to the Setconstructor to create and initialize the subclass instance with the internal state necessary to support theSet.prototype
built-in methods.
24.2.1.1 Set ( [ iterable ] )
When the Set
function is called with optional argument iterable, the following steps are taken:
- If NewTarget is
undefined , throw aTypeError exception. - Let set be ?
OrdinaryCreateFromConstructor (NewTarget,"%Set.prototype%" , « [[SetData]] »). - Set set.[[SetData]] to a new empty
List . - If iterable is either
undefined ornull , return set. - Let adder be ?
Get (set,"add" ). - If
IsCallable (adder) isfalse , throw aTypeError exception. - Let iteratorRecord be ?
GetIterator (iterable). - Repeat,
- Let next be ?
IteratorStep (iteratorRecord). - If next is
false , return set. - Let nextValue be ?
IteratorValue (next). - Let status be
Call (adder, set, « nextValue »). - If status is an
abrupt completion , return ?IteratorClose (iteratorRecord, status).
- Let next be ?
24.2.2 Properties of the Set Constructor
The Set
- has a [[Prototype]] internal slot whose value is
%Function.prototype% . - has the following properties:
24.2.2.1 Set.prototype
The initial value of Set.prototype
is the
This property has the attributes { [[Writable]]:
24.2.2.2 get Set [ @@species ]
Set[@@species]
is an
- Return the
this value.
The value of the
Methods that create derived collection objects should call
24.2.3 Properties of the Set Prototype Object
The Set prototype object:
- is %Set.prototype%.
- has a [[Prototype]] internal slot whose value is
%Object.prototype% . - is an
ordinary object . - does not have a [[SetData]] internal slot.
24.2.3.1 Set.prototype.add ( value )
The following steps are taken:
- Let S be the
this value. - Perform ?
RequireInternalSlot (S, [[SetData]]). - Let entries be the
List that is S.[[SetData]]. - For each element e of entries, do
- If e is not
empty andSameValueZero (e, value) istrue , then- Return S.
- If e is not
- If value is
-0 𝔽, set value to+0 𝔽. - Append value as the last element of entries.
- Return S.
24.2.3.2 Set.prototype.clear ( )
The following steps are taken:
- Let S be the
this value. - Perform ?
RequireInternalSlot (S, [[SetData]]). - Let entries be the
List that is S.[[SetData]]. - For each element e of entries, do
- Replace the element of entries whose value is e with an element whose value is
empty .
- Replace the element of entries whose value is e with an element whose value is
- Return
undefined .
24.2.3.3 Set.prototype.constructor
The initial value of Set.prototype.constructor
is
24.2.3.4 Set.prototype.delete ( value )
The following steps are taken:
- Let S be the
this value. - Perform ?
RequireInternalSlot (S, [[SetData]]). - Let entries be the
List that is S.[[SetData]]. - For each element e of entries, do
- If e is not
empty andSameValueZero (e, value) istrue , then- Replace the element of entries whose value is e with an element whose value is
empty . - Return
true .
- Replace the element of entries whose value is e with an element whose value is
- If e is not
- Return
false .
The value
24.2.3.5 Set.prototype.entries ( )
The following steps are taken:
- Let S be the
this value. - Return ?
CreateSetIterator (S,key+value ).
For iteration purposes, a Set appears similar to a Map where each entry has the same value for its key and value.
24.2.3.6 Set.prototype.forEach ( callbackfn [ , thisArg ] )
When the forEach
method is called with one or two arguments, the following steps are taken:
- Let S be the
this value. - Perform ?
RequireInternalSlot (S, [[SetData]]). - If
IsCallable (callbackfn) isfalse , throw aTypeError exception. - Let entries be the
List that is S.[[SetData]]. - For each element e of entries, do
- If e is not
empty , then- Perform ?
Call (callbackfn, thisArg, « e, e, S »).
- Perform ?
- If e is not
- Return
undefined .
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
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.
24.2.3.7 Set.prototype.has ( value )
The following steps are taken:
- Let S be the
this value. - Perform ?
RequireInternalSlot (S, [[SetData]]). - Let entries be the
List that is S.[[SetData]]. - For each element e of entries, do
- If e is not
empty andSameValueZero (e, value) istrue , returntrue .
- If e is not
- Return
false .
24.2.3.8 Set.prototype.keys ( )
The initial value of the
For iteration purposes, a Set appears similar to a Map where each entry has the same value for its key and value.
24.2.3.9 get Set.prototype.size
Set.prototype.size
is an
- Let S be the
this value. - Perform ?
RequireInternalSlot (S, [[SetData]]). - Let entries be the
List that is S.[[SetData]]. - Let count be 0.
- For each element e of entries, do
- If e is not
empty , set count to count + 1.
- If e is not
- Return
𝔽 (count).
24.2.3.10 Set.prototype.values ( )
The following steps are taken:
- Let S be the
this value. - Return ?
CreateSetIterator (S,value ).
24.2.3.11 Set.prototype [ @@iterator ] ( )
The initial value of the
24.2.3.12 Set.prototype [ @@toStringTag ]
The initial value of the
This property has the attributes { [[Writable]]:
24.2.4 Properties of Set Instances
Set instances are ordinary objects that inherit properties from the Set prototype. Set instances also have a [[SetData]] internal slot.
24.2.5 Set Iterator Objects
A Set Iterator is an
24.2.5.1 CreateSetIterator ( set, kind )
The abstract operation CreateSetIterator takes arguments set and kind. This operation is used to create iterator objects for Set methods that return such iterators. It performs the following steps when called:
Assert : kind iskey+value orvalue .- Perform ?
RequireInternalSlot (set, [[SetData]]). - Let closure be a new
Abstract Closure with no parameters that captures set and kind and performs the following steps when called:- Let index be 0.
- Let entries be the
List that is set.[[SetData]]. - Let numEntries be the number of elements of entries.
- Repeat, while index < numEntries,
- Let e be entries[index].
- Set index to index + 1.
- If e is not
empty , then- If kind is
key+value , then- Perform ?
Yield (!CreateArrayFromList (« e, e »)).
- Perform ?
- Else,
- NOTE: the number of elements in entries may have changed while execution of this abstract operation was paused by
Yield . - Set numEntries to the number of elements of entries.
- If kind is
- Return
undefined .
- Return !
CreateIteratorFromClosure (closure,"%SetIteratorPrototype%" ,%SetIteratorPrototype% ).
24.2.5.2 The %SetIteratorPrototype% Object
The %SetIteratorPrototype% object:
- has properties that are inherited by all Set Iterator Objects.
- is an
ordinary object . - has a [[Prototype]] internal slot whose value is
%IteratorPrototype% . - has the following properties:
24.2.5.2.1 %SetIteratorPrototype%.next ( )
- Return ?
GeneratorResume (this value,empty ,"%SetIteratorPrototype%" ).
24.2.5.2.2 %SetIteratorPrototype% [ @@toStringTag ]
The initial value of the
This property has the attributes { [[Writable]]: