Stage 4 Draft / November 17, 2015

Array.prototype.includes

1Array.prototype.includes ( searchElement [ , fromIndex ] )#

Note 1

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.

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.

When the includes method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let len be ? ToLength(? Get(O, "length")).
  3. If len is 0, return false.
  4. Let n be ? ToInteger(fromIndex). (If fromIndex is undefined, this step produces the value 0.)
  5. If n ≥ 0, then
    1. Let k be n.
  6. Else n < 0,
    1. Let k be len + n.
    2. If k < 0, then let k be 0.
  7. Repeat, while k < len
    1. Let elementK be the result of ? Get(O, ? ToString(k)).
    2. If ? SameValueZero(searchElement, elementK) is true, return true.
    3. Increase k by 1.
  8. Return false.

The length property of the includes method is 1.

Note 2 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. Note 3 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.

2%TypedArray%.prototype.includes ( searchElement [ , fromIndex ] )#

%TypedArray%.prototype.includes is a distinct function that implements the same algorithm as Array.prototype.includes as defined in 1 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.

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.

The length property of the includes method is 1.

3Array.prototype [ @@unscopables ]#

The initial value of the @@unscopables data property is an object created by the following steps:

  1. Let blackList be ObjectCreate(null).
  2. Perform CreateDataProperty(blackList, "copyWithin", true).
  3. Perform CreateDataProperty(blackList, "entries", true).
  4. Perform CreateDataProperty(blackList, "fill", true).
  5. Perform CreateDataProperty(blackList, "find", true).
  6. Perform CreateDataProperty(blackList, "findIndex", true).
  7. Perform CreateDataProperty(blackList, "includes", true).
  8. Perform CreateDataProperty(blackList, "keys", true).
  9. Perform CreateDataProperty(blackList, "values", true).
  10. Assert: Each of the above calls will return true.
  11. Return blackList.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

Note

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.