Normative: Add array-find-from-last (#2476)

Author: Kingwl

spec.html

@@ -37384,6 +37384,62 @@ <h1>Array.prototype.findIndex ( _predicate_ [ , _thisArg_ ] )</h1>
         </emu-note>
       </emu-clause>
 
+      <emu-clause id="sec-array.prototype.findlast">
+        <h1>Array.prototype.findLast ( _predicate_ [ , _thisArg_ ] )</h1>
+        <emu-note>
+          <p>_predicate_ should be a function that accepts three arguments and returns a value that is coercible to a Boolean value. `findLast` calls _predicate_ once for each element of the array, in descending index order, until it finds one where _predicate_ returns *true*. If such an element is found, `findLast` immediately returns that element value. Otherwise, `findLast` returns *undefined*.</p>
+          <p>If a _thisArg_ parameter is provided, it will be used as the *this* value for each invocation of _predicate_. If it is not provided, *undefined* is used instead.</p>
+          <p>_predicate_ is called with three arguments: the element, the index of the element in the array, and the object being traversed.</p>
+          <p>`findLast` does not directly mutate the object on which it is called but the object may be mutated by the calls to _predicate_.</p>
+          <p>The range of elements processed by `findLast` is set before the first call to _predicate_. Elements that are appended to the array after the call to `findLast` begins will not be visited by _predicate_. If existing elements of the array are changed, their value as passed to _predicate_ will be the value at the time that `findLast` visits them.</p>
+        </emu-note>
+        <p>When the `findLast` method is called, the following steps are taken:</p>
+        <emu-alg>
+          1. Let _O_ be ? ToObject(*this* value).
+          1. Let _len_ be ? LengthOfArrayLike(_O_).
+          1. If IsCallable(_predicate_) is *false*, throw a *TypeError* exception.
+          1. Let _k_ be _len_ - 1.
+          1. Repeat, while _k_ &ge; 0,
+            1. Let _Pk_ be ! ToString(𝔽(_k_)).
+            1. Let _kValue_ be ? Get(_O_, _Pk_).
+            1. Let _testResult_ be ToBoolean(? Call(_predicate_, _thisArg_, &laquo; _kValue_, 𝔽(_k_), _O_ &raquo;)).
+            1. If _testResult_ is *true*, return _kValue_.
+            1. Set _k_ to _k_ - 1.
+          1. Return *undefined*.
+        </emu-alg>
+        <emu-note>
+          <p>The `findLast` 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-array.prototype.findlastindex">
+        <h1>Array.prototype.findLastIndex ( _predicate_ [ , _thisArg_ ] )</h1>
+        <emu-note>
+          <p>_predicate_ should be a function that accepts three arguments and returns a value that is coercible to a Boolean value. `findLastIndex` calls _predicate_ once for each element of the array, in descending index order, until it finds one where _predicate_ returns *true*. If such an element is found, `findLastIndex` immediately returns the index of that element value. Otherwise, `findLastIndex` returns -1.</p>
+          <p>If a _thisArg_ parameter is provided, it will be used as the *this* value for each invocation of _predicate_. If it is not provided, *undefined* is used instead.</p>
+          <p>_predicate_ is called with three arguments: the element, the index of the element in the array, and the object being traversed.</p>
+          <p>`findLastIndex` does not directly mutate the object on which it is called but the object may be mutated by the calls to _predicate_.</p>
+          <p>The range of elements processed by `findLastIndex` is set before the first call to _predicate_. Elements that are appended to the array after the call to `findLastIndex` begins will not be visited by _predicate_. If existing elements of the array are changed, their value as passed to _predicate_ will be the value at the time that `findLastIndex` visits them.</p>
+        </emu-note>
+        <p>When the `findLastIndex` method is called, the following steps are taken:</p>
+        <emu-alg>
+          1. Let _O_ be ? ToObject(*this* value).
+          1. Let _len_ be ? LengthOfArrayLike(_O_).
+          1. If IsCallable(_predicate_) is *false*, throw a *TypeError* exception.
+          1. Let _k_ be _len_ - 1.
+          1. Repeat, while _k_ &ge; 0,
+            1. Let _Pk_ be ! ToString(𝔽(_k_)).
+            1. Let _kValue_ be ? Get(_O_, _Pk_).
+            1. Let _testResult_ be ToBoolean(? Call(_predicate_, _thisArg_, &laquo; _kValue_, 𝔽(_k_), _O_ &raquo;)).
+            1. If _testResult_ is *true*, return 𝔽(_k_).
+            1. Set _k_ to _k_ - 1.
+          1. Return *-1*<sub>𝔽</sub>.
+        </emu-alg>
+        <emu-note>
+          <p>The `findLastIndex` 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-array.prototype.flat">
         <h1>Array.prototype.flat ( [ _depth_ ] )</h1>
         <p>When the `flat` method is called, the following steps are taken:</p>
@@ -38203,6 +38259,8 @@ <h1>Array.prototype [ @@unscopables ]</h1>
           1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"fill"*, *true*).
           1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"find"*, *true*).
           1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"findIndex"*, *true*).
+          1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"findLast"*, *true*).
+          1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"findLastIndex"*, *true*).
           1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"flat"*, *true*).
           1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"flatMap"*, *true*).
           1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"includes"*, *true*).
@@ -38876,6 +38934,48 @@ <h1>%TypedArray%.prototype.findIndex ( _predicate_ [ , _thisArg_ ] )</h1>
         <p>This function is not generic. The *this* value must be an object with a [[TypedArrayName]] internal slot.</p>
       </emu-clause>
 
+      <emu-clause id="sec-%typedarray%.prototype.findlast">
+        <h1>%TypedArray%.prototype.findLast ( _predicate_ [ , _thisArg_ ] )</h1>
+        <p>The interpretation and use of the arguments of %TypedArray%`.prototype.findLast` are the same as for `Array.prototype.findLast` as defined in <emu-xref href="#sec-array.prototype.findlast"></emu-xref>.</p>
+        <p>When the `findLast` method is called, the following steps are taken:</p>
+        <emu-alg>
+          1. Let _O_ be the *this* value.
+          1. Perform ? ValidateTypedArray(_O_).
+          1. Let _len_ be _O_.[[ArrayLength]].
+          1. If IsCallable(_predicate_) is *false*, throw a *TypeError* exception.
+          1. Let _k_ be _len_ - 1.
+          1. Repeat, while _k_ &ge; 0,
+            1. Let _Pk_ be ! ToString(𝔽(_k_)).
+            1. Let _kValue_ be ! Get(_O_, _Pk_).
+            1. Let _testResult_ be ToBoolean(? Call(_predicate_, _thisArg_, &laquo; _kValue_, 𝔽(_k_), _O_ &raquo;)).
+            1. If _testResult_ is *true*, return _kValue_.
+            1. Set _k_ to _k_ - 1.
+          1. Return *undefined*.
+        </emu-alg>
+        <p>This function is not generic. The *this* value must be an object with a [[TypedArrayName]] internal slot.</p>
+      </emu-clause>
+
+      <emu-clause id="sec-%typedarray%.prototype.findlastindex">
+        <h1>%TypedArray%.prototype.findLastIndex ( _predicate_ [ , _thisArg_ ] )</h1>
+        <p>The interpretation and use of the arguments of %TypedArray%`.prototype.findLastIndex` are the same as for `Array.prototype.findLastIndex` as defined in <emu-xref href="#sec-array.prototype.findlastindex"></emu-xref>.</p>
+        <p>When the `findLastIndex` method is called, the following steps are taken:</p>
+        <emu-alg>
+          1. Let _O_ be the *this* value.
+          1. Perform ? ValidateTypedArray(_O_).
+          1. Let _len_ be _O_.[[ArrayLength]].
+          1. If IsCallable(_predicate_) is *false*, throw a *TypeError* exception.
+          1. Let _k_ be _len_ - 1.
+          1. Repeat, while _k_ &ge; 0,
+            1. Let _Pk_ be ! ToString(𝔽(_k_)).
+            1. Let _kValue_ be ! Get(_O_, _Pk_).
+            1. Let _testResult_ be ToBoolean(? Call(_predicate_, _thisArg_, &laquo; _kValue_, 𝔽(_k_), _O_ &raquo;)).
+            1. If _testResult_ is *true*, return 𝔽(_k_).
+            1. Set _k_ to _k_ - 1.
+          1. Return *-1*<sub>𝔽</sub>.
+        </emu-alg>
+        <p>This function is not generic. The *this* value must be an object with a [[TypedArrayName]] internal slot.</p>
+      </emu-clause>
+
       <emu-clause id="sec-%typedarray%.prototype.foreach">
         <h1>%TypedArray%.prototype.forEach ( _callbackfn_ [ , _thisArg_ ] )</h1>
         <p>The interpretation and use of the arguments of %TypedArray%`.prototype.forEach` are the same as for `Array.prototype.forEach` as defined in <emu-xref href="#sec-array.prototype.foreach"></emu-xref>.</p>