Add groupByMap

jridgewell · jridgewell · commit c2af54da936a · 2021-10-27T09:54:45.000-04:00
diff --git a/index.html b/index.html
@@ -1095,7 +1095,7 @@
 });
 
 let sdoMap = JSON.parse(`{}`);
-let biblio = JSON.parse(`{"refsByClause":{"sec-array.prototype.groupby":["_ref_0","_ref_1","_ref_2","_ref_3","_ref_4","_ref_5","_ref_6","_ref_7","_ref_8","_ref_9"]},"entries":[{"type":"clause","id":"sec-scope","aoid":null,"titleHTML":"Scope","number":"1","referencingIds":[],"key":"Scope"},{"type":"clause","id":"sec-array.prototype.groupby","aoid":null,"titleHTML":"Array.prototype.groupBy ( <var>callbackfn</var> [ , <var>thisArg</var> ] )","number":"2.1","referencingIds":[],"key":"Array.prototype.groupBy ( callbackfn [ , thisArg ] )"},{"type":"clause","id":"sec-properties-of-the-array-prototype-object","aoid":null,"titleHTML":"Properties of the Array Prototype Object (<a href=\\"https://tc39.es/ecma262/#sec-properties-of-the-array-prototype-object\\">22.1.3</a>)","number":"2","referencingIds":[],"key":"Properties of the Array Prototype Object (22.1.3)"},{"type":"clause","id":"sec-copyright-and-software-license","aoid":null,"titleHTML":"Copyright &amp; Software License","number":"A","referencingIds":[],"key":"Copyright & Software License"}]}`);
+let biblio = JSON.parse(`{"refsByClause":{"sec-array.prototype.groupby":["_ref_0","_ref_1","_ref_2","_ref_3","_ref_4","_ref_5","_ref_6","_ref_7","_ref_8","_ref_9"],"sec-array.prototype.groupbymap":["_ref_10","_ref_11","_ref_12","_ref_13","_ref_14","_ref_15","_ref_16","_ref_17","_ref_18","_ref_19"]},"entries":[{"type":"clause","id":"sec-scope","aoid":null,"titleHTML":"Scope","number":"1","referencingIds":[],"key":"Scope"},{"type":"clause","id":"sec-array.prototype.groupby","aoid":null,"titleHTML":"Array.prototype.groupBy ( <var>callbackfn</var> [ , <var>thisArg</var> ] )","number":"2.1","referencingIds":[],"key":"Array.prototype.groupBy ( callbackfn [ , thisArg ] )"},{"type":"clause","id":"sec-array.prototype.groupbymap","aoid":null,"titleHTML":"Array.prototype.groupByMap ( <var>callbackfn</var> [ , <var>thisArg</var> ] )","number":"2.2","referencingIds":[],"key":"Array.prototype.groupByMap ( callbackfn [ , thisArg ] )"},{"type":"clause","id":"sec-properties-of-the-array-prototype-object","aoid":null,"titleHTML":"Properties of the Array Prototype Object (<a href=\\"https://tc39.es/ecma262/#sec-properties-of-the-array-prototype-object\\">22.1.3</a>)","number":"2","referencingIds":[],"key":"Properties of the Array Prototype Object (22.1.3)"},{"type":"clause","id":"sec-copyright-and-software-license","aoid":null,"titleHTML":"Copyright &amp; Software License","number":"A","referencingIds":[],"key":"Copyright & Software License"}]}`);
 ;let usesMultipage = false</script><style>body {
   display: flex;
   font-size: 18px;
@@ -2240,7 +2240,7 @@
 .normative-optional-tag a {
   color: #884400;
 }
-</style></head><body><div id="menu-toggle">☰</div><div id="menu-spacer"></div><div id="menu"><div id="menu-search"><input type="text" id="menu-search-box" placeholder="Search..."><div id="menu-search-results" class="inactive"></div></div><div id="menu-pins"><div class="menu-pane-header">Pins</div><ul id="menu-pins-list"></ul></div><div class="menu-pane-header">Table of Contents</div><div id="menu-toc"><ol class="toc"><li><span class="item-toggle-none"></span><a href="#sec-scope" title="Scope"><span class="secnum">1</span> Scope</a></li><li><span class="item-toggle">◢</span><a href="#sec-properties-of-the-array-prototype-object" title="Properties of the Array Prototype Object (22.1.3)"><span class="secnum">2</span> Properties of the Array Prototype Object (</a><a href="https://tc39.es/ecma262/#sec-properties-of-the-array-prototype-object">22.1.3</a>)<ol class="toc"><li><span class="item-toggle-none"></span><a href="#sec-array.prototype.groupby" title="Array.prototype.groupBy ( callbackfn [ , thisArg ] )"><span class="secnum">2.1</span> Array.prototype.groupBy ( <var>callbackfn</var> [ , <var>thisArg</var> ] )</a></li></ol></li><li><span class="item-toggle-none"></span><a href="#sec-copyright-and-software-license" title="Copyright &amp; Software License"><span class="secnum">A</span> Copyright &amp; Software License</a></li></ol></div></div><div id="spec-container"><h1 class="version">Stage 2 Draft / October 27, 2021</h1><h1 class="title">Array Grouping</h1>
+</style></head><body><div id="menu-toggle">☰</div><div id="menu-spacer"></div><div id="menu"><div id="menu-search"><input type="text" id="menu-search-box" placeholder="Search..."><div id="menu-search-results" class="inactive"></div></div><div id="menu-pins"><div class="menu-pane-header">Pins</div><ul id="menu-pins-list"></ul></div><div class="menu-pane-header">Table of Contents</div><div id="menu-toc"><ol class="toc"><li><span class="item-toggle-none"></span><a href="#sec-scope" title="Scope"><span class="secnum">1</span> Scope</a></li><li><span class="item-toggle">◢</span><a href="#sec-properties-of-the-array-prototype-object" title="Properties of the Array Prototype Object (22.1.3)"><span class="secnum">2</span> Properties of the Array Prototype Object (</a><a href="https://tc39.es/ecma262/#sec-properties-of-the-array-prototype-object">22.1.3</a>)<ol class="toc"><li><span class="item-toggle-none"></span><a href="#sec-array.prototype.groupby" title="Array.prototype.groupBy ( callbackfn [ , thisArg ] )"><span class="secnum">2.1</span> Array.prototype.groupBy ( <var>callbackfn</var> [ , <var>thisArg</var> ] )</a></li><li><span class="item-toggle-none"></span><a href="#sec-array.prototype.groupbymap" title="Array.prototype.groupByMap ( callbackfn [ , thisArg ] )"><span class="secnum">2.2</span> Array.prototype.groupByMap ( <var>callbackfn</var> [ , <var>thisArg</var> ] )</a></li></ol></li><li><span class="item-toggle-none"></span><a href="#sec-copyright-and-software-license" title="Copyright &amp; Software License"><span class="secnum">A</span> Copyright &amp; Software License</a></li></ol></div></div><div id="spec-container"><h1 class="version">Stage 2 Draft / October 27, 2021</h1><h1 class="title">Array Grouping</h1>
 
 <emu-clause id="sec-scope">
   <h1><span class="secnum">1</span> Scope</h1>
@@ -2270,6 +2270,25 @@ <h1><span class="secnum">2.1</span> Array.prototype.groupBy ( <var>callbackfn</v
     </div></emu-note>
   </emu-clause>
   </ins>
+
+  <ins class="block">
+  <emu-clause id="sec-array.prototype.groupbymap">
+    <h1><span class="secnum">2.2</span> Array.prototype.groupByMap ( <var>callbackfn</var> [ , <var>thisArg</var> ] )</h1>
+    <emu-note><span class="note">Note 1</span><div class="note-contents">
+      <p><var>callbackfn</var> should be a function that accepts three arguments and returns any value. <code>groupByMap</code> calls <var>callbackfn</var> 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 <var>thisArg</var> parameter is provided, it will be used as the <emu-val>this</emu-val> value for each invocation of <var>callbackfn</var>. If it is not provided, <emu-val>undefined</emu-val> is used instead.</p>
+      <p><var>callbackfn</var> is called with three arguments: the value of the element, the index of the element, and the object being traversed.</p>
+      <p><code>groupByMap</code> does not directly mutate the object on which it is called but the object may be mutated by the calls to <var>callbackfn</var>.</p>
+      <p>The range of elements processed by <code>groupByMap</code> is set before the first call to <var>callbackfn</var>. Elements which are appended to the array after the call to <code>groupByMap</code> begins will not be visited by <var>callbackfn</var>. If existing elements of the array are changed their value as passed to <var>callbackfn</var> will be the value at the time <code>groupByMap</code> visits them; elements that are deleted after the call to <code>groupByMap</code> begins and before being visited are not visited.</p>
+      <p>The return value of <code>groupByMap</code> is a Map.</p>
+    </div></emu-note>
+    <p>When the <code>groupByMap</code> method is called with one or two arguments, the following steps are taken:</p>
+    <emu-alg><ol><li>Let <var>O</var> be ?&nbsp;<emu-xref aoid="ToObject" id="_ref_10"><a href="https://tc39.es/ecma262/#sec-toobject">ToObject</a></emu-xref>(<emu-val>this</emu-val> value).</li><li>Let <var>len</var> be ?&nbsp;<emu-xref aoid="LengthOfArrayLike" id="_ref_11"><a href="https://tc39.es/ecma262/#sec-lengthofarraylike">LengthOfArrayLike</a></emu-xref>(<var>O</var>).</li><li>If <emu-xref aoid="IsCallable" id="_ref_12"><a href="https://tc39.es/ecma262/#sec-iscallable">IsCallable</a></emu-xref>(<var>callbackfn</var>) is <emu-val>false</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>k</var> be 0.</li><li>Let <var>groups</var> be a new empty <emu-xref href="#sec-list-and-record-specification-type"><a href="https://tc39.es/ecma262/#sec-list-and-record-specification-type">List</a></emu-xref>.</li><li>Repeat, while <var>k</var> &lt; <var>len</var><ol><li>Let <var>Pk</var> be !&nbsp;<emu-xref aoid="ToString" id="_ref_13"><a href="https://tc39.es/ecma262/#sec-tostring">ToString</a></emu-xref>(<emu-xref href="#𝔽"><a href="https://tc39.es/ecma262/#𝔽">𝔽</a></emu-xref>(<var>k</var>)).</li><li>Let <var>kValue</var> be ?&nbsp;<emu-xref aoid="Get" id="_ref_14"><a href="https://tc39.es/ecma262/#sec-get-o-p">Get</a></emu-xref>(<var>O</var>, <var>Pk</var>).</li><li>Let <var>propertyKey</var> be ?&nbsp;<emu-xref aoid="ToPropertyKey" id="_ref_15"><a href="https://tc39.es/ecma262/#sec-topropertykey">ToPropertyKey</a></emu-xref>(? <emu-xref aoid="Call" id="_ref_16"><a href="https://tc39.es/ecma262/#sec-call">Call</a></emu-xref>(<var>callbackfn</var>, <var>thisArg</var>, « <var>kValue</var>, <emu-xref href="#𝔽"><a href="https://tc39.es/ecma262/#𝔽">𝔽</a></emu-xref>(<var>k</var>), <var>O</var> »)).</li><li>Let <var>group</var> be <emu-const>empty</emu-const>.</li><li>For each <emu-xref href="#sec-list-and-record-specification-type"><a href="https://tc39.es/ecma262/#sec-list-and-record-specification-type">Record</a></emu-xref> { [[Key]], [[Elements]] } <var>g</var> of <var>groups</var>, do<ol><li>If !&nbsp;<emu-xref aoid="SameValueNonNumeric" id="_ref_17"><a href="https://tc39.es/ecma262/#sec-samevaluenonnumeric">SameValueNonNumeric</a></emu-xref>(<var>g</var>.[[Key]], <var>propertyKey</var>) is <emu-val>true</emu-val>, then<ol><li>Set <var>group</var> to <var>g</var>.</li></ol></li></ol></li><li>If <var>group</var> is <emu-const>empty</emu-const>, then<ol><li>Let <var>elements</var> be a new empty <emu-xref href="#sec-list-and-record-specification-type"><a href="https://tc39.es/ecma262/#sec-list-and-record-specification-type">List</a></emu-xref>.</li><li>Set <var>group</var> to the <emu-xref href="#sec-list-and-record-specification-type"><a href="https://tc39.es/ecma262/#sec-list-and-record-specification-type">Record</a></emu-xref> { [[Key]]: <var>propertyKey</var>, [[Elements]]: <var>elements</var> }.</li><li>Append <var>group</var> as the last element of <var>groups</var>.</li></ol></li><li>Append <var>kValue</var> as the last element of <var>group</var>.[[Elements]].</li><li>Set <var>k</var> to <var>k</var> + 1.</li></ol></li><li>Let <var>map</var> be !&nbsp;<emu-xref aoid="Construct" id="_ref_18"><a href="https://tc39.es/ecma262/#sec-construct">Construct</a></emu-xref>(<emu-xref href="#sec-map-constructor"><a href="https://tc39.es/ecma262/#sec-map-constructor">%Map%</a></emu-xref>).</li><li>For each <emu-xref href="#sec-list-and-record-specification-type"><a href="https://tc39.es/ecma262/#sec-list-and-record-specification-type">Record</a></emu-xref> { [[Key]], [[Elements]] } <var>g</var> of <var>groups</var>, do<ol><li>Let <var>elements</var> be !&nbsp;<emu-xref aoid="CreateArrayFromList" id="_ref_19"><a href="https://tc39.es/ecma262/#sec-createarrayfromlist">CreateArrayFromList</a></emu-xref>(<var>g</var>.[[Elements]]).</li><li>Let <var>entry</var> be the <emu-xref href="#sec-list-and-record-specification-type"><a href="https://tc39.es/ecma262/#sec-list-and-record-specification-type">Record</a></emu-xref> { [[Key]]: <var>g</var>.[[Key]], [[Value]]: <var>elements</var> }.</li><li>Append <var>entry</var> as the last element of <var>map</var>.[[MapData]].</li></ol></li><li>Return <var>map</var>.</li></ol></emu-alg>
+    <emu-note><span class="note">Note 2</span><div class="note-contents">
+      <p>The <code>groupBy</code> function is intentionally generic; it does not require that its <emu-val>this</emu-val> value be an Array object. Therefore it can be transferred to other kinds of objects for use as a method.</p>
+    </div></emu-note>
+  </emu-clause>
+  </ins>
 </emu-clause><emu-annex id="sec-copyright-and-software-license">
       <h1><span class="secnum">A</span> Copyright &amp; Software License</h1>
       
diff --git a/spec.emu b/spec.emu
@@ -64,4 +64,49 @@ location: https://tc39.es/proposal-array-grouping/
     </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 not visited.</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_ &lt; _len_
+        1. Let _Pk_ be ! ToString(𝔽(_k_)).
+        1. Let _kValue_ be ? Get(_O_, _Pk_).
+        1. Let _propertyKey_ be ? ToPropertyKey(? Call(_callbackfn_, _thisArg_, &laquo; _kValue_, 𝔽(_k_), _O_ &raquo;)).
+        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 _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>
+  </ins>
 </emu-clause>
