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
117 lines (112 loc) · 7.3 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
<!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: 2
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 and returns a value that is coercible to a property. `groupBy` calls _callbackfn_ once for each element in the array, in ascending order, and constructs a new object of arrays, where the property key is the return value and array is filled with the items that return that 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.groupByMap ( _callbackfn_ [ , _thisArg_ ] )</h1>
<emu-note>
<p>_callbackfn_ should be a function that accepts three arguments and returns any value. `groupByMap` calls _callbackfn_ once for each element in the array, in ascending order, and constructs a new Map of arrays, where the key is the return value and array is filled with the items that return that 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>`groupByMap` 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 `groupByMap` is set before the first call to _callbackfn_. Elements which are appended to the array after the call to `groupByMap` 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 `groupByMap` visits them; elements that are deleted after the call to `groupByMap` 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 `groupByMap` is a Map.</p>
</emu-note>
<p>When the `groupByMap` 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 `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>
<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. If _groups_ contains a Record _g_ such that ! SameValueZero(_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. Else,
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>