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
67 lines (64 loc) · 4.02 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
<!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 not visited.</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. Let _group_ be ~empty~.
1. For each Record { [[Key]], [[Elements]] } _g_ of _groups_, do
1. If ! SameValueNonNumeric(_g_.[[Key]], _propertyKey_) is *true*, then
1. Set _group_ to _g_.
1. If _group_ is ~empty~, then
1. Let _elements_ be a new empty List.
1. Set _group_ to the Record { [[Key]]: _propertyKey_, [[Elements]]: _elements_ }.
1. Append _group_ as the last element of _groups_.
1. Append _kValue_ as the last element of _group_.[[Elements]].
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>
</emu-clause>