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

.[perex]{data-version:4.0.4}
[api:Nette\Utils\Iterables] статичний клас з функціями для роботи з ітераторами. Його аналогом для масивів є [Nette\Utils\Arrays |arrays].


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

```shell
composer require nette/utils
```

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

```php
use Nette\Utils\Iterables;
```


contains(iterable $iterable, $value): bool .[method]
----------------------------------------------------

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

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

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


containsKey(iterable $iterable, $key): bool .[method]
-----------------------------------------------------

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

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


every(iterable $iterable, callable $predicate): bool .[method]
--------------------------------------------------------------

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

```php
$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 .[method]
--------------------------------------------------------------------

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

```php
$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 .[method]
-------------------------------------------------------------------------------------------

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

```php
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 .[method]
----------------------------------------------------------------------------------------------

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

```php
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 .[method]
-------------------------------------------------------------------

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

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

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


mapWithKeys(iterable $iterable, callable $transformer): Generator .[method]
---------------------------------------------------------------------------

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

```php
$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 .[method]
--------------------------------------------------------

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

```php
$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 .[method]
-------------------------------------------------------------

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

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

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

Див. опис [методу every() |#every()].


toIterator(iterable $iterable): Iterator .[method]
--------------------------------------------------

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

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

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