Please support this book: buy it (PDF, EPUB, MOBI) or donate

3. Array.prototype.includes

This chapter describes the ECMAScript 2016 feature “Array.prototype.includes” by Domenic Denicola and Rick Waldron.

3.1 Overview

  1. > ['a', 'b', 'c'].includes('a')
  2. true
  3. > ['a', 'b', 'c'].includes('d')
  4. false

3.2 The Array method includes

The Array method includes has the following signature:

  1. Array.prototype.includes(value : any) : boolean

It returns true if value is an element of its receiver (this) and false, otherwise:

  1. > ['a', 'b', 'c'].includes('a')
  2. true
  3. > ['a', 'b', 'c'].includes('d')
  4. false

includes is similar to indexOf – the following two expressions are mostly equivalent:

  1. arr.includes(x)
  2. arr.indexOf(x) >= 0

The main difference is that includes() finds NaN, whereas indexOf() doesn’t:

  1. > [NaN].includes(NaN)
  2. true
  3. > [NaN].indexOf(NaN)
  4. -1

includes does not distinguish between +0 and -0 (which is how almost all of JavaScript works):

  1. > [-0].includes(+0)
  2. true

Typed Arrays will also have a method includes():

  1. let tarr = Uint8Array.of(12, 5, 3);
  2. console.log(tarr.includes(5)); // true

3.3 Frequently asked questions

  • Why is the method called includes and not contains?The latter was the initial choice, but that broke code on the web (MooTools adds this method to Array.prototype).
  • Why is the method called includes and not has?has is used for keys (Map.prototype.has), includes is used for elements (String.prototype.includes). The elements of a Set can be viewed as being both keys and values, which is why there is a Set.prototype.has (and no includes).
  • The ES6 method String.prototype.includes works with strings, not characters. Isn’t that inconsistent w.r.t. Array.prototype.includes?If Array includes worked exactly like string includes, it would accept arrays, not single elements. But the two includes follow the example of indexOf; characters are seen as a special case and strings with arbitrary lengths as the general case.

3.4 Further reading