Práce s iterátory
*****************

.[perex]{data-version:4.0.4}
[api:Nette\Utils\Iterables] je statická třída s funkcemi pro práci s iterátory. Její obdobou pro pole je [Nette\Utils\Arrays|arrays].


Instalace:

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

Všechny příklady předpokládají vytvořený alias:

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


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

Hledá zadanou hodnotu v iterátoru. Používá striktní porovnání (`===`) pro ověření shody. Vrací `true`, pokud je hodnota nalezena, jinak `false`.

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

Tato metoda je užitečná, když potřebujete rychle zjistit, zda se konkrétní hodnota v iterátoru nachází, aniž byste museli procházet všechny prvky ručně.


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

Hledá zadaný klíč v iterátoru. Používá striktní porovnání (`===`) pro ověření shody. Vrací `true`, pokud je klíč nalezen, jinak `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]
--------------------------------------------------------------

Ověřuje, zda všechny prvky iterátoru splňují podmínku definovanou v `$predicate`. Funkce `$predicate` má signaturu `function ($value, $key, iterable $iterable): bool` a musí vracet `true` pro každý prvek, aby metoda `every()` vrátila `true`.

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

Tato metoda je užitečná pro ověření, zda všechny prvky v kolekci splňují určitou podmínku, například zda jsou všechna čísla menší než určitá hodnota.


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

Vytváří nový iterátor, který obsahuje pouze ty prvky z původního iterátoru, které splňují podmínku definovanou v `$predicate`. Funkce `$predicate` má signaturu `function ($value, $key, iterable $iterable): bool` a musí vracet `true` pro prvky, které mají být zachovány.

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

Metoda využívá generátor, což znamená, že filtrování probíhá postupně při procházení výsledku. To je efektivní z hlediska paměti a umožňuje zpracovávat i velmi velké kolekce. Pokud neprojdete všechny prvky výsledného iterátoru, ušetříte výpočetní výkon, protože se nezpracují všechny prvky původního iterátoru.


first(iterable $iterable, ?callable $predicate=null, ?callable $else=null): mixed .[method]
-------------------------------------------------------------------------------------------

Vrací první prvek iterátoru. Pokud je zadán `$predicate`, vrací první prvek, který splňuje danou podmínku. Funkce `$predicate` má signaturu `function ($value, $key, iterable $iterable): bool`. Pokud není nalezen žádný vyhovující prvek, volá se funkce `$else` (pokud je zadána) a vrací se její výsledek. Pokud `$else` není zadáno, vrací se `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
```

Tato metoda je užitečná, když potřebujete rychle získat první prvek kolekce nebo první prvek splňující určitou podmínku, aniž byste museli procházet celou kolekci ručně.


firstKey(iterable $iterable, ?callable $predicate=null, ?callable $else=null): mixed .[method]
----------------------------------------------------------------------------------------------

Vrací klíč prvního prvku iterátoru. Pokud je zadán `$predicate`, vrací klíč prvního prvku, který splňuje danou podmínku. Funkce `$predicate` má signaturu `function ($value, $key, iterable $iterable): bool`. Pokud není nalezen žádný vyhovující prvek, volá se funkce `$else` (pokud je zadána) a vrací se její výsledek. Pokud `$else` není zadáno, vrací se `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]
-------------------------------------------------------------------

Vytváří nový iterátor aplikováním funkce `$transformer` na každý prvek původního iterátoru. Funkce `$transformer` má signaturu `function ($value, $key, iterable $iterable): mixed` a její návratová hodnota se použije jako nová hodnota prvku.

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

Metoda využívá generátor, což znamená, že transformace probíhá postupně při procházení výsledku. To je efektivní z hlediska paměti a umožňuje zpracovávat i velmi velké kolekce. Pokud neprojdete všechny prvky výsledného iterátoru, ušetříte výpočetní výkon, protože se nezpracují všechny prvky původního iterátoru.


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

Vytváří nový iterátor transformací hodnot a klíčů původního iterátoru. Funkce `$transformer` má signaturu `function ($value, $key, iterable $iterable): ?array{$newKey, $newValue}`. Pokud `$transformer` vrátí `null`, prvek je přeskočen. Pro zachované prvky se první prvek vráceného pole použije jako nový klíč a druhý prvek jako nová hodnota.

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

Stejně jako `map()`, tato metoda využívá generátor pro postupné zpracování a efektivní práci s pamětí. To umožňuje pracovat s velkými kolekcemi a šetřit výpočetní výkon při částečném průchodu výsledkem.


memoize(iterable $iterable): IteratorAggregate .[method]
--------------------------------------------------------

Vytváří obal kolem iterátoru, který během iterace ukládá do mezipaměti jeho klíče a hodnoty. To umožňuje opakovanou iteraci dat bez nutnosti znovu procházet původní zdroj dat.

```php
$iterator = /* data, která nelze iterovat vícekrát */
$memoized = Iterables::memoize($iterator);
// Nyní můžete iterovat $memoized vícekrát bez ztráty dat
```

Tato metoda je užitečná v situacích, kdy potřebujete vícekrát projít stejnou sadu dat, ale původní iterátor neumožňuje opakovanou iteraci nebo by opakované procházení bylo nákladné (např. při čtení dat z databáze nebo souboru).


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

Ověřuje, zda alespoň jeden prvek iterátoru splňuje podmínku definovanou v `$predicate`. Funkce `$predicate` má signaturu `function ($value, $key, iterable $iterable): bool` a musí vracet `true` pro alespoň jeden prvek, aby metoda `some()` vrátila `true`.

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

Tato metoda je užitečná pro rychlé ověření, zda v kolekci existuje alespoň jeden prvek splňující určitou podmínku, například zda kolekce obsahuje alespoň jedno sudé číslo.

Viz [#every()].


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

Převádí jakýkoliv iterovatelný objekt (array, Traversable) na Iterator. Pokud je vstup již Iterator, vrátí ho beze změny.

```php
$array = [1, 2, 3];
$iterator = Iterables::toIterator($array);
// Nyní máte Iterator místo pole
```

Tato metoda je užitečná, když potřebujete zajistit, že máte k dispozici Iterator, bez ohledu na typ vstupních dat. To může být užitečné při vytváření funkcí, které pracují s různými typy iterovatelných dat.