Функции на итератора
********************

.[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) в итератор. Ако входният обект вече е Iterator, той се връща непроменен.

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

Този метод е полезен, когато трябва да се уверите, че имате Iterator, независимо от типа на входните данни. Това може да бъде полезно при създаване на функции, които работят с различни типове итерационни данни.