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
61 lines (58 loc) · 3.71 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
<!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: 1
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. _callbackfn_ is called only for elements of the array which actually exist; it is not called for missing elements of the array.</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>
</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 _obj_ be ! OrdinaryObjectCreate(%Object.prototype%).
1. Assert: _obj_ is an extensible ordinary object with no own properties.
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 _seen_ be ? HasOwnProperty(_obj_, _propertyKey_).
1. If _seen_ is *true*, then
1. Let _arr_ be ! Get(_obj_, _propertyKey_).
1. Else
1. Let _arr_ be ? ArraySpeciesCreate(O, 0).
1. Perform ! CreateDataPropertyOrThrow(_obj_, _propertyKey_, _arr_).
1. Perform ? Call(%Array.prototype.push%, _arr_, _kValue_).
1. Set _k_ to _k_ + 1.
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>