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

.[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]
----------------------------------------------------

Перевіряє наявність значення в ітераторі. Використовує строге порівняння (`===`).

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


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

Перевіряє наявність ключа в ітераторі. Використовує строге порівняння (`===`).

```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` з сигнатурою `function ($value, $key, iterable $iterable): bool`.

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

Див. [функцію some() |#some()].


filter(iterable $iterable, callable $predicate): Generator .[method]
--------------------------------------------------------------------

Ітератор, який фільтрує елементи за предикатом. Предикат має сигнатуру `function ($value, $key, iterable $iterable): bool`. Зберігає оригінальні ключі.

```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]
-------------------------------------------------------------------------------------------

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

```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]
----------------------------------------------------------------------------------------------

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

```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): array .[method]
---------------------------------------------------------------

Ітератор, що перетворює значення шляхом виклику `$transformer`. Має сигнатуру `function ($value, $key, iterable $iterable): bool`. Зберігає оригінальні ключі.

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


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

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

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

Див. [функцію every() |#every()].