Array.prototype.values()

Метод values() экземпляров Array возвращает новый объект итератора массива, который итерирует значение каждого элемента в массиве.

Попробовать

const array = ["a", "b", "c"];
const iterator = array.values();

for (const value of iterator) {
  console.log(value);
}

// Expected output: "a"
// Expected output: "b"
// Expected output: "c"

Синтаксис

values()

Параметры

Нет.

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

Новый итерируемый объект-итератор.

Описание

Array.prototype.values() является реализацией по умолчанию для Array.prototype[Symbol.iterator]().

Array.prototype.values === Array.prototype[Symbol.iterator]; // true

При использовании для разреженных массивов, метод values() итерирует пустые слоты, как если бы они имели значение undefined.

Метод values() является обобщённым. Он ожидает, что значение this будет иметь свойство length и свойства с целочисленными ключами.

Примеры

Итерация с использованием цикла for...of

Поскольку values() возвращает итерируемый итератор, вы можете использовать цикл for...of для его итерации.

const arr = ["a", "b", "c", "d", "e"];
const iterator = arr.values();

for (const letter of iterator) {
  console.log(letter);
} // "a" "b" "c" "d" "e"

Итерация с использованием next()

Поскольку возвращаемое значение также является итератором, вы можете напрямую вызвать его метод next().

const arr = ["a", "b", "c", "d", "e"];
const iterator = arr.values();
iterator.next(); // { value: "a", done: false }
iterator.next(); // { value: "b", done: false }
iterator.next(); // { value: "c", done: false }
iterator.next(); // { value: "d", done: false }
iterator.next(); // { value: "e", done: false }
iterator.next(); // { value: undefined, done: true }
console.log(iterator.next().value); // undefined

Повторное использование итерируемого объекта

Итерируемый объект, возвращаемый values(), не является многоразовым. Когда next().done = true или currentIndex > length, цикл for...of завершается, и дальнейшая итерация не имеет эффекта.

const arr = ["a", "b", "c", "d", "e"];
const values = arr.values();
for (const letter of values) {
  console.log(letter);
}
// "a" "b" "c" "d" "e"
for (const letter of values) {
  console.log(letter);
}
// No output

Если вы используете оператор break для досрочного завершения итерации, итератор может возобновить работу с текущей позиции при продолжении итерации.

const arr = ["a", "b", "c", "d", "e"];
const values = arr.values();
for (const letter of values) {
  console.log(letter);
  if (letter === "b") {
    break;
  }
}
// "a" "b"

for (const letter of values) {
  console.log(letter);
}
// "c" "d" "e"

Изменения во время итерации

В объекте итератора массива, возвращаемом values(), не хранятся значения; вместо этого он хранит адрес массива, использованного при его создании, и считывает текущий посещаемый индекс при каждой итерации. Следовательно, результат итерации зависит от значения, хранящегося по этому индексу в момент шага. Если значения в массиве изменились, значения объекта итератора массива также меняются.

const arr = ["a", "b", "c", "d", "e"];
const iterator = arr.values();
console.log(iterator); // Array Iterator { }
console.log(iterator.next().value); // "a"
arr[1] = "n";
console.log(iterator.next().value); // "n"

В отличие от итеративных методов, объект итератора массива не сохраняет длину массива в момент своего создания, а считывает её один раз при каждой итерации. Следовательно, если массив увеличивается во время итерации, итератор также посетит новые элементы. Это может привести к бесконечным циклам.

const arr = [1, 2, 3];
for (const e of arr) {
  arr.push(e * 10);
}
// RangeError: invalid array length

Итерация разреженных массивов

values() будет посещать пустые слоты, как если бы они были undefined.

for (const element of [, "a"].values()) {
  console.log(element);
}
// undefined
// 'a'

Вызов values() для объектов, не являющихся массивами

Метод values() считывает свойство length объекта this, а затем обращается к каждому свойству, ключ которого является неотрицательным целым числом, меньшим length.

const arrayLike = {
  length: 3,
  0: "a",
  1: "b",
  2: "c",
  3: "d", // ignored by values() since length is 3
};
for (const entry of Array.prototype.values.call(arrayLike)) {
  console.log(entry);
}
// a
// b
// c

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

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

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

• Полифил Array.prototype.values в core-js
• Полифил es-shims для Array.prototype.values
• Руководство по индексированным коллекциям
• Array
• Array.prototype.entries()
• Array.prototype.keys()
• Array.prototype[Symbol.iterator]()
• TypedArray.prototype.values()
• Протоколы итерации