Iterátor funkciók

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.

Telepítés:

composer require nette/utils

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

use Nette\Utils\Iterables;

contains (iterable $iterable, $value): bool

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.

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

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.

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

every (iterable $iterable, callable $predicate): bool

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.

$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

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.

$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

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.

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

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.

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

Ú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.

$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

Ú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.

$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

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.

$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

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.

$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().

toIterator (iterable $iterable): Iterator

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.

$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.