This repository has been archived by the owner on Nov 27, 2023. It is now read-only.
generated from tc39/template-for-proposals
/
spec.emu
135 lines (127 loc) · 6.12 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
<!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: 4
contributors: Justin Ridgewell, Jordan Harband
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-object-constructor">
<h1>Properties of the Object Constructor (<a href="https://tc39.es/ecma262/multipage/fundamental-objects.html#sec-properties-of-the-object-constructor">20.1.2</a>)</h1>
<ins class="block">
<emu-clause id="sec-object.groupby">
<h1>Object.groupBy ( _items_, _callbackfn_ )</h1>
<emu-note>
<p>_callbackfn_ should be a function that accepts two arguments. `groupBy` calls _callbackfn_ once for each element in _items_, 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>_callbackfn_ is called with two arguments: the value of the element and the index of the element.</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 two arguments, the following steps are taken:</p>
<emu-alg>
1. Let _groups_ be ? GroupBy(_items_, _callbackfn_, ~property~).
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-clause>
</ins>
</emu-clause>
<emu-clause id="sec-properties-of-the-map-constructor">
<h1>Properties of the Map Constructor (<a href="https://tc39.es/ecma262/multipage/keyed-collections.html#sec-properties-of-the-map-constructor">24.1.2</a>)</h1>
<ins class="block">
<emu-clause id="sec-map.groupby">
<h1>Map.groupBy ( _items_, _callbackfn_ )</h1>
<emu-note>
<p>_callbackfn_ should be a function that accepts two arguments. `groupBy` calls _callbackfn_ once for each element in _items_, 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>_callbackfn_ is called with two arguments: the value of the element and the index of the element.</p>
<p>The return value of `groupBy` is a Map.</p>
</emu-note>
<p>When the `groupBy` method is called with two arguments, the following steps are taken:</p>
<emu-alg>
1. Let _groups_ be ? GroupBy(_items_, _callbackfn_, ~zero~).
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_ to _map_.[[MapData]].
1. Return _map_.
</emu-alg>
</emu-clause>
</ins>
</emu-clause>
<emu-clause id="sec-group-by-helpers">
<h1>Group By Helpers</h1>
<ins class="block">
<emu-clause id="sec-group-by" type="abstract operation">
<h1>
GroupBy (
_items_: an ECMAScript language value,
_callbackfn_: an ECMAScript language value,
_keyCoercion_: ~property~ or ~zero~,
): either a normal completion containing a List of Records with fields [[Key]] (an ECMAScript language value) and [[Elements]] (a List of ECMAScript language values), or a throw completion
</h1>
<dl class="header">
</dl>
<emu-alg>
1. Perform ? RequireObjectCoercible(_items_).
1. If IsCallable(_callbackfn_) is *false*, throw a *TypeError* exception.
1. Let _groups_ be a new empty List.
1. Let _iteratorRecord_ be ? GetIterator(_items_).
1. Let _k_ be 0.
1. Repeat,
1. If _k_ ≥ 2<sup>53</sup> - 1, then
1. Let _error_ be ThrowCompletion(a newly created *TypeError* object).
1. Return ? IteratorClose(_iteratorRecord_, _error_).
1. Let _next_ be ? IteratorStep(_iteratorRecord_).
1. If _next_ is *false*, then
1. Return _groups_.
1. Let _value_ be ? IteratorValue(_next_).
1. Let _key_ be Completion(Call(_callbackfn_, *undefined*, « _value_, 𝔽(_k_) »)).
1. IfAbruptCloseIterator(_key_, _iteratorRecord_).
1. If _keyCoercion_ is ~property~, then
1. Set _key_ to Completion(ToPropertyKey(_key_)).
1. IfAbruptCloseIterator(_key_, _iteratorRecord_).
1. Else,
1. Assert: _keyCoercion_ is ~zero~.
1. If _key_ is *-0*<sub>𝔽</sub>, set _key_ to *+0*<sub>𝔽</sub>.
1. Perform AddValueToKeyedGroup(_groups_, _key_, _value_).
1. Set _k_ to _k_ + 1.
</emu-alg>
</emu-clause>
</ins>
<ins class="block">
<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,
): ~unused~
</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_ to _g_.[[Elements]].
1. Return ~unused~.
1. Let _group_ be the Record { [[Key]]: _key_, [[Elements]]: « _value_ » }.
1. Append _group_ to _groups_.
1. Return ~unused~.
</emu-alg>
</emu-clause>
</ins>
</emu-clause>