This repository has been archived by the owner on Jun 7, 2022. It is now read-only.
generated from tc39/template-for-proposals
-
Notifications
You must be signed in to change notification settings - Fork 11
/
spec.html
165 lines (161 loc) · 8.81 KB
/
spec.html
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
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
<!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: Proposal-array-find-from-last
stage: 4
contributors: Wenlu Wang, Daniel Rosenwasser
</pre>
<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 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 value of the element, the index of the element, 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_ ≥ 0,
1. Let _Pk_ be ! ToString(𝔽(_k_)).
1. Let _kValue_ be ? Get(_O_, _Pk_).
1. Let _testResult_ be ! ToBoolean(? Call(_predicate_, _thisArg_, « _kValue_, 𝔽(_k_), _O_ »)).
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 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 value of the element, the index of the element, 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_ ≥ 0,
1. Let _Pk_ be ! ToString(𝔽(_k_)).
1. Let _kValue_ be ? Get(_O_, _Pk_).
1. Let _testResult_ be ! ToBoolean(? Call(_predicate_, _thisArg_, « _kValue_, 𝔽(_k_), _O_ »)).
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-@@unscopables">
<h1>Array.prototype [ @@unscopables ]</h1>
<p>The initial value of the @@unscopables <emu-xref href="#sec-object-type">data property</emu-xref> is an object created by the following steps:</p>
<emu-alg>
1. Let _unscopableList_ be OrdinaryObjectCreate(*null*).
1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"copyWithin"*, *true*).
1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"entries"*, *true*).
1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"fill"*, *true*).
1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"find"*, *true*).
1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"findIndex"*, *true*).
1. <ins>Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"findLast"*, *true*). </ins>
1. <ins>Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"findLastIndex"*, *true*). </ins>
1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"flat"*, *true*).
1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"flatMap"*, *true*).
1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"includes"*, *true*).
1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"keys"*, *true*).
1. Perform ! CreateDataPropertyOrThrow(_unscopableList_, *"values"*, *true*).
</emu-alg>
<p>
This property has the attributes { [[Writable]]: *false*, [[Enumerable]]: *false*, [[Configurable]]: *true* }.
</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_ ≥ 0,
1. Let _Pk_ be ! ToString(𝔽(_k_)).
1. Let _kValue_ be ! Get(_O_, _Pk_).
1. Let _testResult_ be ! ToBoolean(? Call(_predicate_, _thisArg_, « _kValue_, 𝔽(_k_), _O_ »)).
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_ ≥ 0,
1. Let _Pk_ be ! ToString(𝔽(_k_)).
1. Let _kValue_ be ! Get(_O_, _Pk_).
1. Let _testResult_ be ! ToBoolean(? Call(_predicate_, _thisArg_, « _kValue_, 𝔽(_k_), _O_ »)).
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>