Iterator.zipKeyed()

Статический метод Iterator.zipKeyed() создает новый объект Iterator, который агрегирует элементы из нескольких итерируемых объектов, выдавая объекты, содержащие элементы на одной позиции, с ключами, указанными во входных данных. По сути, он "объединяет" входные итерируемые объекты, позволяя одновременно их итерировать.

Метод Iterator.zip() похож, но выдает массивы вместо объектов.

Синтаксис

Iterator.zipKeyed(iterables)
Iterator.zipKeyed(iterables, options)

Параметры

iterables

Объект. Ключ каждого свойства используется в качестве ключа в результирующих объектах. Значение свойства должно реализовывать либо протокол iterable, либо, в противном случае, протокол iterator. Эти итерируемые объекты могут быть бесконечными. Строки отклоняются: чтобы объединять строки, явно преобразуйте их в итераторы с помощью Iterator.from().

options Необязательно

Объект, определяющий поведение в случае несогласованных длин входных данных. Он может иметь следующие свойства:

mode Необязательно

Одно из следующих значений:

• "shortest" (по умолчанию): Результирующий итератор останавливается, когда один входной итерируемый объект исчерпан.
• "longest": Результирующий итератор останавливается, когда все входные итерируемые объекты исчерпаны. Пропущенные значения из более коротких итерируемых объектов заполняются согласно опции padding.
• "strict": Будет выброшено TypeError, если не все входные итерируемые объекты завершаются одновременно.

padding Необязательно

Объект. Извлекается и проверяется только тогда, когда mode равно "longest". Если undefined или отсутствует, пропущенные значения из более коротких итерируемых объектов заполняются undefined (что эквивалентно передаче пустого объекта). Если предоставлен объект, каждый ключ аргумента iterables извлекается *сразу же после вызова Iterator.zipKeyed()*. padding[key] используется для пропущенных значений iterables[key]. Если объект padding не имеет некоторых ключей, эти ключи заполняются undefined.

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

Новый объект Iterator. Каждый из его элементов — это объект с теми же ключами, что и аргумент iterables, содержащий элементы из каждого входного итерируемого объекта в соответствующей позиции.

Описание

Функция Iterator.zipKeyed() ведет себя так же, как Iterator.zip(); единственное отличие заключается в том, что вы можете указать ключи, используемые в результирующих объектах, в то время как Iterator.zip() всегда использует числовые индексы (выдавая массивы).

Если представить итерируемые объекты как массивы, входные данные могут выглядеть так:

({
  a: [a1, a2, a3, a4],
  b: [b1, b2, b3],
  c: [c1, c2, c3, c4, c5],
});

Результирующий итератор, независимо от опций, начнет с выдачи следующих массивов:

({ a: a1, b: b1, c: c1 });
({ a: a2, b: b2, c: c2 });
({ a: a3, b: b3, c: c3 });

После выдачи первых трех объектов входной итерируемый объект b исчерпывается при четвертом вызове next() — он возвращает { done: true }. Что произойдет дальше, зависит от опции mode. Если mode равно "shortest" (по умолчанию), результирующий итератор останавливается здесь: два других входных итератора закрываются. Если mode равно "strict", выбрасывается ошибка, поскольку два других итерируемых объекта *не* завершены, когда второй выдает результат { done: true }. Если mode равно "longest", результирующий итератор продолжает выдавать объекты, заполняя пропущенные значения. Например, если padding не предоставлено, оно по умолчанию равно undefined:

({ a: a4, b: undefined, c: c4 });
({ a: undefined, b: undefined, c: c5 });

Если padding предоставлено в виде объекта, оно может выглядеть как { a: p1, b: p2, c: p3 }. Затем p2 используется для заполнения пропущенного значения из входного итерируемого объекта b, а p1 используется для заполнения пропущенного значения из входного итерируемого объекта a:

({ a: a4, b: p2, c: c4 });
({ a: p1, b: p2, c: c5 });

Примеры

Транспонирование табличных данных

Существует два распространенных способа представления табличных данных: как объект, где каждое свойство является столбцом, или как массив объектов, где каждый объект является строкой. Этот пример показывает, как можно итерировать представление, основанное на столбцах, по строкам с помощью Iterator.zipKeyed().

const table = {
  name: ["Caroline", "Danielle", "Evelyn"],
  age: [30, 25, 35],
  city: ["New York", "London", "Hong Kong"],
};

for (const { name, age, city } of Iterator.zipKeyed(table)) {
  console.log(`${name}, aged ${age}, lives in ${city}.`);
}

// Output:
// Caroline, aged 30, lives in New York.
// Danielle, aged 25, lives in London.
// Evelyn, aged 35, lives in Hong Kong.

Большинство вариантов использования Iterator.zipKeyed() идентичны таковым для Iterator.zip(). Какой из них использовать, зависит от того, есть ли у вас уже объект итерируемых объектов (используйте zipKeyed()) или массив итерируемых объектов (используйте zip()). Мы рекомендуем использовать zipKeyed(), когда это возможно, поскольку указание явных ключей затрудняет случайное перепутывание порядка итерируемых объектов.

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

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

См. также

• Polyfill Iterator.zipKeyed в core-js
• Polyfill Iterator.zipKeyed из es-shims
• Iterator
• Iterator.zip()
• Iterator.from()
• Iterator.concat()