Iterator.prototype.includes()

Метод includes() экземпляров Iterator похож на Array.prototype.includes(): он возвращает true, если находит элемент, равный заданному значению. В противном случае, если итератор исчерпан, но такой элемент не найден, он возвращает false.

Синтаксис

includes(searchElement)
includes(searchElement, fromIndex)

Параметры

searchElement

Значение для поиска.

fromIndex Необязательный

Индекс, основанный на нуле, с которого начинается поиск. Должен быть неотрицательным целым числом, Infinity, или undefined. Если fromIndex больше или равен количеству элементов, сгенерированных итератором (включая случай, когда fromIndex является Infinity), метод всегда возвращает false после исчерпания итератора. Если fromIndex является undefined, по умолчанию используется 0.

Возвращаемое значение

Логическое значение, которое равно true, если значение searchElement найдено в итераторе (или в части итератора, начиная с fromIndex, если указано).

Исключения

TypeError

Генерируется, если fromIndex не является одним из следующих типов: целое число, Infinity, -Infinity, или undefined.

RangeError

Генерируется, если fromIndex отрицателен.

Описание

Метод includes() сравнивает searchElement с элементами массива, используя алгоритм SameValueZero. Этот алгоритм работает как строгое равенство === (где -0 и +0 считаются равными), за исключением того, что NaN считается равным самому себе.

В отличие от Array.prototype.includes(), параметр fromIndex в Iterator.prototype.includes() не может быть отрицательным, поскольку итератор не имеет известной длины. Проверка типа также более строгая: нецелочисленные значения не отсекаются до целых чисел.

Основное преимущество вспомогательных функций итератора над методами массива заключается в том, что они являются ленивыми, то есть они генерируют следующее значение только по запросу. Это позволяет избежать ненужных вычислений, а также дает возможность использовать их с бесконечными итераторами. С бесконечными итераторами includes() возвращает true, как только найдено первое совпадение. Если значение никогда не встречается, метод никогда не возвращает результат.

Вызов includes() всегда закрывает базовый итератор, даже если метод возвращает результат досрочно. Итератор никогда не остается в промежуточном состоянии.

Примеры

Использование includes()

function* fibonacci() {
  let current = 1;
  let next = 1;
  while (true) {
    yield current;
    [current, next] = [next, current + next];
  }
}

console.log(fibonacci().includes(8)); // true
console.log(fibonacci().take(10).includes(7)); // false
console.log(fibonacci().includes(7)); // Never completes

Метод закрывает итератор после возврата.

const seq = fibonacci();
console.log(seq.includes(8)); // true
console.log(seq.next()); // { value: undefined, done: true }

Использование fromIndex

fromIndex указывает количество элементов, которые нужно пропустить с начала. Это эквивалентно вызову drop(fromIndex).includes(searchElement).

function* fibonacci() {
  let current = 1;
  let next = 1;
  while (true) {
    yield current;
    [current, next] = [next, current + next];
  }
}

console.log(fibonacci().includes(8, 3)); // true
console.log(fibonacci().includes(8, 10)); // false

Если fromIndex больше или равен доступным элементам, возвращается false.

["a", "b", "c"].values().includes("a", 3); // false

Спецификации

Совместимость с браузерами

Смотрите также

• полифилл es-shims для Iterator.prototype.includes
• Iterator
• Iterator.prototype.every()
• Iterator.prototype.find()
• Iterator.prototype.some()
• Array.prototype.includes()