This repository was archived by the owner on Nov 27, 2023. It is now read-only.
generated from tc39/template-for-proposals
-
Notifications
You must be signed in to change notification settings - Fork 17
/
Copy pathspec.emu
144 lines (138 loc) · 9.44 KB
/
spec.emu
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
<!doctype html>
<meta charset="utf8">
<link rel="stylesheet" href="./spec.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/8.4/styles/github.min.css">
<script src="./spec.js"></script>
<pre class="metadata">
title: Array Grouping
status: proposal
stage: 3
contributors: Justin Ridgewell
location: https://tc39.es/proposal-array-grouping/
</pre>
<emu-clause id="sec-scope">
<h1>Scope</h1>
<p>
This is the spec text of the <a href="https://github.com/tc39/proposal-array-grouping/">Array Grouping proposal</a> in ECMAScript.
</p>
</emu-clause>
<emu-clause id="sec-properties-of-the-array-prototype-object">
<h1>Properties of the Array Prototype Object (<a href="https://tc39.es/ecma262/#sec-properties-of-the-array-prototype-object">22.1.3</a>)</h1>
<ins class="block">
<emu-clause id="sec-array.prototype.groupby">
<h1>Array.prototype.groupBy ( _callbackfn_ [ , _thisArg_ ] )</h1>
<emu-note>
<p>_callbackfn_ should be a function that accepts three arguments. `groupBy` calls _callbackfn_ once for each element in the array, in ascending order, and constructs a new object of arrays. Each value returned by _callbackfn_ is coerced to a property key, and the associated element is included in the array in the constructed object according to this property key.</p>
<p>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.</p>
<p>_callbackfn_ is called with three arguments: the value of the element, the index of the element, and the object being traversed.</p>
<p>`groupBy` does not directly mutate the object on which it is called but the object may be mutated by the calls to _callbackfn_.</p>
<p>The range of elements processed by `groupBy` is set before the first call to _callbackfn_. Elements which are appended to the array after the call to `groupBy` begins will not be visited by _callbackfn_. If existing elements of the array are changed their value as passed to _callbackfn_ will be the value at the time `groupBy` visits them; elements that are deleted after the call to `groupBy` begins and before being visited are still visited and are either looked up from the prototype or are *undefined*.</p>
<p>The return value of `groupBy` is an object that does not inherit from _Object.prototype_.</p>
</emu-note>
<p>When the `groupBy` method is called with one or two arguments, the following steps are taken:</p>
<emu-alg>
1. Let _O_ be ? ToObject(*this* value).
1. Let _len_ be ? LengthOfArrayLike(_O_).
1. If IsCallable(_callbackfn_) is *false*, throw a *TypeError* exception.
1. Let _k_ be 0.
1. Let _groups_ be a new empty List.
1. Repeat, while _k_ < _len_
1. Let _Pk_ be ! ToString(𝔽(_k_)).
1. Let _kValue_ be ? Get(_O_, _Pk_).
1. Let _propertyKey_ be ? ToPropertyKey(? Call(_callbackfn_, _thisArg_, « _kValue_, 𝔽(_k_), _O_ »)).
1. Perform ! AddValueToKeyedGroup(_groups_, _propertyKey_, _kValue_).
1. Set _k_ to _k_ + 1.
1. Let _obj_ be ! OrdinaryObjectCreate(*null*).
1. For each Record { [[Key]], [[Elements]] } _g_ of _groups_, do
1. Let _elements_ be ! CreateArrayFromList(_g_.[[Elements]]).
1. Perform ! CreateDataPropertyOrThrow(_obj_, _g_.[[Key]], _elements_).
1. Return _obj_.
</emu-alg>
<emu-note>
<p>The `groupBy` function is intentionally generic; it does not require that its *this* value be an Array object. Therefore it can be transferred to other kinds of objects for use as a method.</p>
</emu-note>
</emu-clause>
</ins>
<ins class="block">
<emu-clause id="sec-array.prototype.groupbymap">
<h1>Array.prototype.groupByToMap ( _callbackfn_ [ , _thisArg_ ] )</h1>
<emu-note>
<p>_callbackfn_ should be a function that accepts three arguments. `groupByToMap` calls _callbackfn_ once for each element in the array, in ascending order, and constructs a new Map of arrays. Each value returned by _callbackfn_ is used as a key in the Map, and the associated element is included in the array in the constructed Map according to this key.</p>
<p>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.</p>
<p>_callbackfn_ is called with three arguments: the value of the element, the index of the element, and the object being traversed.</p>
<p>`groupByToMap` does not directly mutate the object on which it is called but the object may be mutated by the calls to _callbackfn_.</p>
<p>The range of elements processed by `groupByToMap` is set before the first call to _callbackfn_. Elements which are appended to the array after the call to `groupByToMap` begins will not be visited by _callbackfn_. If existing elements of the array are changed their value as passed to _callbackfn_ will be the value at the time `groupByToMap` visits them; elements that are deleted after the call to `groupByToMap` begins and before being visited are still visited and are either looked up from the prototype or are *undefined*.</p>
<p>The return value of `groupByToMap` is a Map.</p>
</emu-note>
<p>When the `groupByToMap` method is called with one or two arguments, the following steps are taken:</p>
<emu-alg>
1. Let _O_ be ? ToObject(*this* value).
1. Let _len_ be ? LengthOfArrayLike(_O_).
1. If IsCallable(_callbackfn_) is *false*, throw a *TypeError* exception.
1. Let _k_ be 0.
1. Let _groups_ be a new empty List.
1. Repeat, while _k_ < _len_
1. Let _Pk_ be ! ToString(𝔽(_k_)).
1. Let _kValue_ be ? Get(_O_, _Pk_).
1. Let _key_ be ? Call(_callbackfn_, _thisArg_, « _kValue_, 𝔽(_k_), _O_ »).
1. If _key_ is *-0*<sub>𝔽</sub>, set _key_ to *+0*<sub>𝔽</sub>.
1. Perform ! AddValueToKeyedGroup(_groups_, _key_, _kValue_).
1. Set _k_ to _k_ + 1.
1. Let _map_ be ! Construct(%Map%).
1. For each Record { [[Key]], [[Elements]] } _g_ of _groups_, do
1. Let _elements_ be ! CreateArrayFromList(_g_.[[Elements]]).
1. Let _entry_ be the Record { [[Key]]: _g_.[[Key]], [[Value]]: _elements_ }.
1. Append _entry_ as the last element of _map_.[[MapData]].
1. Return _map_.
</emu-alg>
<emu-note>
<p>The `groupByToMap` function is intentionally generic; it does not require that its *this* value be an Array object. Therefore it can be transferred to other kinds of objects for use as a method.</p>
</emu-note>
</emu-clause>
<emu-clause id="sec-add-value-to-keyed-group" type="abstract operation">
<h1>
AddValueToKeyedGroup (
_groups_: a List of Records that have [[Key]] and [[Elements]] fields,
_key_: an ECMAScript language value,
_value_: an ECMAScript language value,
)
</h1>
<dl class="header">
</dl>
<emu-alg>
1. For each Record { [[Key]], [[Elements]] } _g_ of _groups_, do
1. If ! SameValue(_g_.[[Key]], _key_) is *true*, then
1. Assert: exactly one element of _groups_ meets this criteria.
1. Append _value_ as the last element of _g_.[[Elements]].
1. Return.
1. Let _group_ be the Record { [[Key]]: _key_, [[Elements]]: « _value_ » }.
1. Append _group_ as the last element of _groups_.
</emu-alg>
</emu-clause>
</ins>
<emu-clause id="sec-array.prototype-@@unscopables">
<h1>Array.prototype [ @@unscopables ]</h1>
<p>The initial value of the @@unscopables data property is an object created by the following steps:</p>
<emu-alg>
1. Let _unscopableList_ be ! OrdinaryObjectCreate(*null*).
1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"at"*, *true*).
1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"copyWithin"*, *true*).
1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"entries"*, *true*).
1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"fill"*, *true*).
1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"find"*, *true*).
1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"findIndex"*, *true*).
1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"flat"*, *true*).
1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"flatMap"*, *true*).
1. <ins>Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"groupBy"*, *true*).</ins>
1. <ins>Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"groupByToMap"*, *true*).</ins>
1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"includes"*, *true*).
1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"keys"*, *true*).
1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"values"*, *true*).
1. Return _unscopableList_.
</emu-alg>
<p>This property has the attributes { [[Writable]]: *false*, [[Enumerable]]: *false*, [[Configurable]]: *true* }.</p>
<emu-note>
<p>The own property names of this object are property names that were not included as standard properties of `Array.prototype` prior to the ECMAScript 2015 specification. These names are ignored for `with` statement binding purposes in order to preserve the behaviour of existing code that might use one of these names as a binding in an outer scope that is shadowed by a `with` statement whose binding object is an Array.</p>
</emu-note>
</emu-clause>
</emu-clause>