Функції ітератора

Nette\Utils\Iterables статичний клас з функціями для роботи з ітераторами. Його аналогом для масивів є Nette\Utils\Arrays.

Встановлення:

composer require nette/utils

У всіх прикладах передбачається, що створено наступний псевдонім:

use Nette\Utils\Iterables;

contains (iterable $iterable, $value): bool

Шукає задане значення в ітераторі. Використовує строге порівняння (===) для перевірки на збіг. Повертає true, якщо значення знайдено, інакше false.

Iterables::contains(new ArrayIterator([1, 2, 3]), 1);    // true
Iterables::contains(new ArrayIterator([1, 2, 3]), '1');  // false

Цей метод корисний, коли вам потрібно швидко визначити, чи присутнє певне значення в ітераторі без ручного перебору всіх елементів.

containsKey (iterable $iterable, $key): bool

Шукає заданий ключ в ітераторі. Використовує строге порівняння (===) для перевірки на збіг. Повертає true, якщо ключ знайдено, інакше false.

Iterables::containsKey(new ArrayIterator([1, 2, 3]), 0);  // true
Iterables::containsKey(new ArrayIterator([1, 2, 3]), 4);  // false

every (iterable $iterable, callable $predicate): bool

Перевіряє, чи всі елементи ітератора задовольняють умову, визначену в $predicate. Функція $predicate має сигнатуру function ($value, $key, iterable $iterable): bool і повинна повертати true для кожного елементу, щоб метод every() повертав true.

$iterator = new ArrayIterator([1, 30, 39, 29, 10, 13]);
$isBelowThreshold = fn($value) => $value < 40;
$res = Iterables::every($iterator, $isBelowThreshold); // true

Цей метод корисний для перевірки того, що всі елементи колекції задовольняють певну умову, наприклад, чи всі числа є меншими за певне значення.

filter (iterable $iterable, callable $predicate): Generator

Створює новий ітератор, який містить тільки ті елементи з початкового ітератора, які задовольняють умову, визначену в $predicate. Функція $predicate має сигнатуру function ($value, $key, iterable $iterable): bool і повинна повернути true для елементів, які слід зберегти.

$iterator = new ArrayIterator([1, 2, 3]);
$iterator = Iterables::filter($iterator, fn($v) => $v < 3);
// 1, 2

Метод використовує генератор, що означає, що фільтрація відбувається інкрементно під час ітерації. Це ефективно використовує пам'ять і дозволяє обробляти дуже великі колекції. Якщо ви не перебираєте всі елементи результуючого ітератора, ви економите обчислювальні зусилля, оскільки не всі елементи початкового ітератора обробляються.

first (iterable $iterable, ?callable $predicate=null, ?callable $else=null): mixed

Повертає перший елемент ітератора. Якщо вказано $predicate, повертається перший елемент, який задовольняє задану умову. Функція $predicate має сигнатуру function ($value, $key, iterable $iterable): bool. Якщо відповідного елемента не знайдено, викликається функція $else (якщо вона задана) і повертається її результат. Якщо $else не задано, повертається null.

Iterables::first(new ArrayIterator([1, 2, 3]));                   // 1
Iterables::first(new ArrayIterator([1, 2, 3]), fn($v) => $v > 2); // 3
Iterables::first(new ArrayIterator([]));                          // null
Iterables::first(new ArrayIterator([]), else: fn() => false);     // false

Цей метод корисний, коли потрібно швидко отримати перший елемент колекції або перший елемент, який задовольняє певну умову, без ручного перебору всієї колекції.

firstKey (iterable $iterable, ?callable $predicate=null, ?callable $else=null): mixed

Повертає ключ першого елемента ітератора. Якщо вказано $predicate, повертає ключ першого елемента, який задовольняє задану умову. Функція $predicate має сигнатуру function ($value, $key, iterable $iterable): bool. Якщо відповідного елемента не знайдено, викликається функція $else (якщо вона передбачена) і повертається її результат. Якщо $else не задано, повертається null.

Iterables::firstKey(new ArrayIterator([1, 2, 3]));                   // 0
Iterables::firstKey(new ArrayIterator([1, 2, 3]), fn($v) => $v > 2); // 2
Iterables::firstKey(new ArrayIterator(['a' => 1, 'b' => 2]));        // 'a'
Iterables::firstKey(new ArrayIterator([]));                          // null

map (iterable $iterable, callable $transformer): Generator

Створює новий ітератор шляхом застосування функції $transformer до кожного елемента початкового ітератора. Функція $transformer має сигнатуру function ($value, $key, iterable $iterable): mixed і її значення, що повертається, використовується як нове значення елемента.

$iterator = new ArrayIterator([1, 2, 3]);
$iterator = Iterables::map($iterator, fn($v) => $v * 2);
// 2, 4, 6

Метод використовує генератор, що означає, що перетворення відбувається інкрементно під час ітерації. Це ефективно використовує пам'ять і дозволяє працювати з дуже великими колекціями. Якщо ви не перебираєте всі елементи результуючого ітератора, ви економите обчислювальні зусилля, оскільки не всі елементи початкового ітератора обробляються.

mapWithKeys (iterable $iterable, callable $transformer): Generator

Створює новий ітератор шляхом перетворення значень і ключів вихідного ітератора. Функція $transformer має сигнатуру function ($value, $key, iterable $iterable): ?array{$newKey, $newValue}. Якщо $transformer повертає null, елемент пропускається. Для збережених елементів перший елемент повернутого масиву використовується як новий ключ, а другий елемент – як нове значення.

$iterator = new ArrayIterator(['a' => 1, 'b' => 2]);
$iterator = Iterables::mapWithKeys($iterator, fn($v, $k) => $v > 1 ? [$v * 2, strtoupper($k)] : null);
// [4 => 'B']

Як і map(), цей метод використовує генератор для інкрементної обробки та ефективності використання пам'яті. Це дозволяє працювати з великими колекціями та економити обчислювальні зусилля, обробляючи лише частину результату.

memoize (iterable $iterable): IteratorAggregate

Створює обгортку навколо ітератора, яка кешує його ключі та значення під час ітерації. Це дозволяє повторювати ітерації над даними без необхідності переробляти початкове джерело даних.

$iterator = /* data that cannot be iterated multiple times */
$memoized = Iterables::memoize($iterator);
// Now you can iterate $memoized multiple times without data loss

Цей метод корисний у ситуаціях, коли вам потрібно повторювати один і той самий набір даних кілька разів, але оригінальний ітератор не підтримує повторні ітерації або повторні ітерації були б дорогими (наприклад, читання даних з бази даних або файлу).

some (iterable $iterable, callable $predicate): bool

Перевіряє, чи хоча б один елемент ітератора задовольняє умову, визначену в $predicate. Функція $predicate має сигнатуру function ($value, $key, iterable $iterable): bool і повинна повернути true для хоча б одного елементу, щоб метод some() повернув true.

$iterator = new ArrayIterator([1, 30, 39, 29, 10, 13]);
$isEven = fn($value) => $value % 2 === 0;
$res = Iterables::some($iterator, $isEven); // true

Цей метод корисний для швидкої перевірки, чи є в колекції хоча б один елемент, який задовольняє певній умові, наприклад, чи містить колекція хоча б одне парне число.

Див. опис методу every().

toIterator (iterable $iterable): Iterator

Перетворює будь-який ітерований об'єкт (масив, Traversable) в ітератор. Якщо на вході вже є ітератор, він повертається без змін.

$array = [1, 2, 3];
$iterator = Iterables::toIterator($array);
// Now you have an Iterator instead of an array

Цей метод корисний, коли вам потрібно переконатися, що у вас є ітератор, незалежно від типу вхідних даних. Це може бути корисно при створенні функцій, які працюють з різними типами даних, що повторюються.