forked from tc39/proposal-Array.prototype.includes
-
Notifications
You must be signed in to change notification settings - Fork 0
/
spec.html
84 lines (71 loc) · 5.07 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
<!DOCTYPE html>
<meta charset="utf-8">
<pre class="metadata">
title: Array.prototype.includes
status: proposal
stage: 4
location: https://tc39.github.io/Array.prototype.includes/
copyright: false
contributors: Domenic Denicola
</pre>
<script src="https://bterlson.github.io/ecmarkup/ecmarkup.js" defer></script>
<link rel="stylesheet" href="https://bterlson.github.io/ecmarkup/elements.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/8.4/styles/solarized_light.min.css">
<emu-clause id="array-prototype-includes">
<h1>Array.prototype.includes ( searchElement [ , fromIndex ] )</h1>
<emu-note>
<p>`includes` compares _searchElement_ to the elements of the array, in ascending order, using the SameValueZero algorithm, and if found at any position, returns *true*; otherwise, *false* is returned.</p>
<p>The optional second argument _fromIndex_ defaults to 0 (i.e. the whole array is searched). If it is greater than or equal to the length of the array, *false* is returned, i.e. the array will not be searched. If it is negative, it is used as the offset from the end of the array to compute _fromIndex_. If the computed index is less than 0, the whole array will be searched.</p>
</emu-note>
<p>When the `includes` method is called, the following steps are taken:</p>
<emu-alg>
1. Let _O_ be ? ToObject(*this* value).
1. Let _len_ be ? ToLength(? Get(_O_, "length")).
1. If _len_ is 0, return *false*.
1. Let _n_ be ? ToInteger(_fromIndex_). (If _fromIndex_ is *undefined*, this step produces the value 0.)
1. If _n_ ≥ 0, then
1. Let _k_ be _n_.
1. Else _n_ < 0,
1. Let _k_ be _len_ + _n_.
1. If _k_ < 0, then let _k_ be 0.
1. Repeat, while _k_ < _len_
1. Let _elementK_ be the result of ? Get(_O_, ? ToString(_k_)).
1. If ? SameValueZero(_searchElement_, _elementK_) is *true*, return *true*.
1. Increase _k_ by 1.
1. Return *false*.
</emu-alg>
<p>The `length` property of the `includes` method is *1*.</p>
<emu-note>
The `includes` 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.
</emu-note>
<emu-note>
The `includes` method intentionally differs from the similar `indexOf` method in two ways. First, it uses the SameValueZero algorithm, instead of Strict Equality Comparison, allowing it to detect *NaN* array elements. Second, it does not skip missing array elements, instead treating them as *undefined*.
</emu-note>
</emu-clause>
<emu-clause id="typedarray-prototype-includes">
<h1>%TypedArray%.prototype.includes ( searchElement [ , fromIndex ] )</h1>
<p>`%TypedArray%.prototype.includes` is a distinct function that implements the same algorithm as `Array.prototype.includes` as defined in <emu-xref href="#array-prototype-includes"></emu-xref> except that the *this* object’s [[ArrayLength]] internal slot is accessed in place of performing a [[Get]] of *"length"*. The implementation of the algorithm may be optimized with the knowledge that the *this* value is an object that has a fixed length and whose integer indexed properties are not sparse. However, such optimization must not introduce any observable changes in the specified behaviour of the algorithm.</p>
<p>This function is not generic. ValidateTypedArray is applied to the *this* value prior to evaluating the algorithm. If its result is an abrupt completion that exception is thrown instead of evaluating the algorithm.</p>
<p>The `length` property of the `includes` method is *1*.</p>
</emu-clause>
<emu-clause id="sec-array.prototype-@@unscopables">
<h1>Array.prototype [ @@unscopables ]</h1>
<p>The initial value of the @@unscopables data property is an object created by the following steps:</p>
<emu-alg>
1. Let _blackList_ be ObjectCreate(*null*).
1. Perform CreateDataProperty(_blackList_, `"copyWithin"`, *true*).
1. Perform CreateDataProperty(_blackList_, `"entries"`, *true*).
1. Perform CreateDataProperty(_blackList_, `"fill"`, *true*).
1. Perform CreateDataProperty(_blackList_, `"find"`, *true*).
1. Perform CreateDataProperty(_blackList_, `"findIndex"`, *true*).
1. <ins>Perform CreateDataProperty(_blackList_, `"includes"`, *true*).</ins>
1. Perform CreateDataProperty(_blackList_, `"keys"`, *true*).
1. Perform CreateDataProperty(_blackList_, `"values"`, *true*).
1. Assert: Each of the above calls will return *true*.
1. Return _blackList_.
</emu-alg>
<p>This property has the attributes { [[Writable]]: *false*, [[Enumerable]]: *false*, [[Configurable]]: *true* }.</p>
<emu-note>
<p>The own property names of this object are property names that were not included as standard properties of `Array.prototype` prior to the ECMAScript 2015 specification. These names are ignored for `with` statement binding purposes in order to preserve the behaviour of existing code that might use one of these names as a binding in an outer scope that is shadowed by a `with` statement whose binding object is an Array object.</p>
</emu-note>
</emu-clause>