Iterátor funkciók
*****************

.[perex]{data-version:4.0.4}
[api:Nette\Utils\Iterables] egy statikus osztály az iterátorokkal való munkához szükséges függvényekkel. A tömbökre vonatkozó megfelelője a [Nette\Utils\Arrays |arrays].


Telepítés:

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

Minden példa feltételezi a következő alias létrehozását:

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


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

Egy adott értéket keres egy iterátorban. Szigorú összehasonlítást (`===`) használ az egyezés ellenőrzésére. Visszaadja a `true` értéket, ha az értéket megtalálta, egyébként `false`.

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

Ez a módszer akkor hasznos, ha gyorsan meg kell állapítani, hogy egy adott érték jelen van-e egy iterátorban anélkül, hogy manuálisan végig kellene iterálni az összes elemet.


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

Egy adott kulcs keresése egy iterátorban. Szigorú összehasonlítást (`===`) használ az egyezés keresésére. Visszaadja `true` ha a kulcsot megtalálta, egyébként `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]
--------------------------------------------------------------

Ellenőrzi, hogy az iterátor minden eleme megfelel-e a `$predicate` pontban meghatározott feltételnek. A `$predicate` függvénynek a `function ($value, $key, iterable $iterable): bool` aláírása van, és minden elemre vissza kell adnia a `true` értéket ahhoz, hogy a `every()` módszer a `true` értéket adja vissza.

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

Ez a módszer hasznos annak ellenőrzésére, hogy egy gyűjtemény minden eleme megfelel-e egy bizonyos feltételnek, például annak, hogy az összes szám egy adott érték alatt van-e.


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

Létrehoz egy új iterátort, amely csak azokat az elemeket tartalmazza az eredeti iterátorból, amelyek megfelelnek a `$predicate` pontban meghatározott feltételnek. A `$predicate` függvény aláírása `function ($value, $key, iterable $iterable): bool`, és a megtartandó elemek esetében a `true` függvényt kell visszaadnia.

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

A módszer generátort használ, ami azt jelenti, hogy a szűrés az iteráció során inkrementálisan történik. Ez memóriahatékony és lehetővé teszi a nagyon nagy gyűjtemények kezelését. Ha nem iteráljuk végig az eredményül kapott iterátor minden elemét, akkor számítási energiát takarítunk meg, mivel az eredeti iterátor nem minden elemét dolgozzuk fel.


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

Visszaadja az iterátor első elemét. Ha a `$predicate` megadva van, akkor az első olyan elemet adja vissza, amely megfelel a megadott feltételnek. A `$predicate` függvény aláírása `function ($value, $key, iterable $iterable): bool`. Ha nem talál megfelelő elemet, akkor a `$else` függvényt (ha megadva van) hívja meg, és annak eredményét adja vissza. Ha a `$else` nincs megadva, akkor a `null` függvényt adja vissza.

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

Ez a módszer akkor hasznos, ha gyorsan ki kell kérni egy gyűjtemény első elemét vagy az első olyan elemet, amely megfelel egy bizonyos feltételnek, anélkül, hogy manuálisan végig kellene iterálni a teljes gyűjteményt.


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

Visszaadja az iterátor első elemének kulcsát. Ha `$predicate` van megadva, akkor a megadott feltételnek megfelelő első elem kulcsát adja vissza. A `$predicate` függvény aláírása `function ($value, $key, iterable $iterable): bool`. Ha nem találunk megfelelő elemet, akkor a `$else` függvényt (ha megadva van) hívja meg, és annak eredményét adja vissza. Ha a `$else` nincs megadva, akkor a `null` függvényt adja vissza.

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

Új iterátort hoz létre a `$transformer` függvénynek az eredeti iterátor minden elemére történő alkalmazásával. A `$transformer` függvény aláírása `function ($value, $key, iterable $iterable): mixed`, és visszatérési értéke az elem új értékeként kerül felhasználásra.

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

A módszer generátort használ, ami azt jelenti, hogy az átalakítás az iteráció során inkrementálisan történik. Ez memóriahatékony és lehetővé teszi a nagyon nagy gyűjtemények kezelését. Ha nem iteráljuk végig az eredményül kapott iterátor minden elemét, akkor számítási erőfeszítést takarítunk meg, mivel az eredeti iterátor nem minden elemét dolgozzuk fel.


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

Új iterátort hoz létre az eredeti iterátor értékeinek és kulcsainak átalakításával. A `$transformer` függvény aláírása: `function ($value, $key, iterable $iterable): ?array{$newKey, $newValue}`. Ha a `$transformer` visszatér `null`, akkor az elemet kihagyja. A megtartott elemek esetében a visszaadott tömb első elemét használja új kulcsként, a második elemet pedig új értékként.

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

A `map()` módszerhez hasonlóan ez a módszer is generátort használ a növekményes feldolgozás és a memóriahatékonyság érdekében. Ez lehetővé teszi a nagy gyűjteményekkel való munkát és a számítási erőfeszítés megtakarítását azáltal, hogy az eredménynek csak egy részét dolgozza fel.


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

Létrehoz egy burkolatot egy iterátor körül, amely az iteráció során a kulcsokat és az értékeket gyorsítótárba helyezi. Ez lehetővé teszi az adatok ismételt iterálását anélkül, hogy az eredeti adatforrást újra fel kellene dolgozni.

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

Ez a módszer olyan helyzetekben hasznos, amikor többször kell ugyanazon az adathalmazon iterálni, de az eredeti iterátor nem támogatja az ismételt iterációt, vagy az ismételt iteráció költséges lenne (pl. adatok olvasása adatbázisból vagy fájlból).


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

Ellenőrzi, hogy az iterátor legalább egy eleme megfelel-e a `$predicate` pontban meghatározott feltételnek. A `$predicate` függvénynek a `function ($value, $key, iterable $iterable): bool` aláírása van, és legalább egy elemre vonatkozóan vissza kell adnia a `true` értéket, hogy a `some()` módszer a `true` értéket adja vissza.

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

Ez a módszer hasznos annak gyors ellenőrzésére, hogy van-e legalább egy olyan elem egy gyűjteményben, amely megfelel egy bizonyos feltételnek, például, hogy a gyűjtemény tartalmaz-e legalább egy páros számot.

Lásd [every() |#every()].


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

Bármilyen iterálható objektumot (tömb, Traversable) Iterátorrá alakít. Ha a bemenet már egy Iterator, akkor azt változatlanul adja vissza.

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

Ez a metódus akkor hasznos, ha a bemeneti adattípustól függetlenül biztosítani kell, hogy egy Iterátorral rendelkezzünk. Ez hasznos lehet olyan függvények létrehozásakor, amelyek különböző típusú iterálható adatokkal dolgoznak.