Delo z iteratorji

Nette\Utils\Iterables je statični razred s funkcijami za delo z iteratorji. Njegova ustreznica za polja je Nette\Utils\Arrays.

Namestitev:

composer require nette/utils

Vsi primeri predpostavljajo ustvarjen alias:

use Nette\Utils\Iterables;

contains (iterable $iterable, $value): bool

Išče podano vrednost v iteratorju. Uporablja strogo primerjavo (===) za preverjanje ujemanja. Vrne true, če je vrednost najdena, sicer false.

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

Ta metoda je uporabna, ko morate hitro ugotoviti, ali se določena vrednost nahaja v iteratorju, ne da bi morali ročno prehajati skozi vse elemente.

containsKey (iterable $iterable, $key): bool

Išče podani ključ v iteratorju. Uporablja strogo primerjavo (===) za preverjanje ujemanja. Vrne true, če je ključ najden, sicer 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

Preverja, ali vsi elementi iteratorja izpolnjujejo pogoj, definiran v $predicate. Funkcija $predicate ima signaturo function ($value, $key, iterable $iterable): bool in mora vrniti true za vsak element, da metoda every() vrne true.

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

Ta metoda je uporabna za preverjanje, ali vsi elementi v zbirki izpolnjujejo določen pogoj, na primer, ali so vsa števila manjša od določene vrednosti.

filter (iterable $iterable, callable $predicate): Generator

Ustvari nov iterator, ki vsebuje samo tiste elemente iz izvirnega iteratorja, ki izpolnjujejo pogoj, definiran v $predicate. Funkcija $predicate ima signaturo function ($value, $key, iterable $iterable): bool in mora vrniti true za elemente, ki naj bodo ohranjeni.

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

Metoda uporablja generator, kar pomeni, da filtriranje poteka postopoma med prehajanjem rezultata. To je učinkovito z vidika pomnilnika in omogoča obdelavo tudi zelo velikih zbirk. Če ne preidete vseh elementov rezultirajočega iteratorja, prihranite računsko moč, saj se ne obdelajo vsi elementi izvirnega iteratorja.

first (iterable $iterable, ?callable $predicate=null, ?callable $else=null): mixed

Vrne prvi element iteratorja. Če je podan $predicate, vrne prvi element, ki izpolnjuje dani pogoj. Funkcija $predicate ima signaturo function ($value, $key, iterable $iterable): bool. Če ni najden noben ustrezen element, se pokliče funkcija $else (če je podana) in vrne se njen rezultat. Če $else ni podan, se vrne null.

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

Ta metoda je uporabna, ko morate hitro pridobiti prvi element zbirke ali prvi element, ki izpolnjuje določen pogoj, ne da bi morali ročno prehajati skozi celotno zbirko.

firstKey (iterable $iterable, ?callable $predicate=null, ?callable $else=null): mixed

Vrne ključ prvega elementa iteratorja. Če je podan $predicate, vrne ključ prvega elementa, ki izpolnjuje dani pogoj. Funkcija $predicate ima signaturo function ($value, $key, iterable $iterable): bool. Če ni najden noben ustrezen element, se pokliče funkcija $else (če je podana) in vrne se njen rezultat. Če $else ni podan, se vrne null.

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

Ustvari nov iterator z uporabo funkcije $transformer na vsakem elementu izvirnega iteratorja. Funkcija $transformer ima signaturo function ($value, $key, iterable $iterable): mixed in njena vrnjena vrednost se uporabi kot nova vrednost elementa.

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

Metoda uporablja generator, kar pomeni, da transformacija poteka postopoma med prehajanjem rezultata. To je učinkovito z vidika pomnilnika in omogoča obdelavo tudi zelo velikih zbirk. Če ne preidete vseh elementov rezultirajočega iteratorja, prihranite računsko moč, saj se ne obdelajo vsi elementi izvirnega iteratorja.

mapWithKeys (iterable $iterable, callable $transformer): Generator

Ustvari nov iterator s transformacijo vrednosti in ključev izvirnega iteratorja. Funkcija $transformer ima signaturo function ($value, $key, iterable $iterable): ?array{$newKey, $newValue}. Če $transformer vrne null, je element preskočen. Za ohranjene elemente se prvi element vrnjenega polja uporabi kot nov ključ, drugi element pa kot nova vrednost.

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

Tako kot map(), ta metoda uporablja generator za postopno obdelavo in učinkovito delo s pomnilnikom. To omogoča delo z velikimi zbirkami in prihranek računske moči pri delnem prehodu rezultata.

memoize (iterable $iterable): IteratorAggregate

Ustvari ovoj okoli iteratorja, ki med iteracijo shranjuje njegove ključe in vrednosti v predpomnilnik. To omogoča ponovno iteracijo podatkov brez potrebe po ponovnem prehodu izvirnega vira podatkov.

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

Ta metoda je uporabna v situacijah, ko morate večkrat preiti isti nabor podatkov, vendar izvirni iterator ne omogoča ponovne iteracije ali pa bi bilo ponovno prehajanje drago (npr. pri branju podatkov iz podatkovne baze ali datoteke).

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

Preverja, ali vsaj en element iteratorja izpolnjuje pogoj, definiran v $predicate. Funkcija $predicate ima signaturo function ($value, $key, iterable $iterable): bool in mora vrniti true za vsaj en element, da metoda some() vrne true.

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

Ta metoda je uporabna za hitro preverjanje, ali v zbirki obstaja vsaj en element, ki izpolnjuje določen pogoj, na primer, ali zbirka vsebuje vsaj eno sodo število.

Glejte every().

toIterator (iterable $iterable): Iterator

Pretvori kateri koli iterabilni objekt (array, Traversable) v Iterator. Če je vhod že Iterator, ga vrne nespremenjenega.

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

Ta metoda je uporabna, ko morate zagotoviti, da imate na voljo Iterator, ne glede na vrsto vhodnih podatkov. To je lahko uporabno pri ustvarjanju funkcij, ki delajo z različnimi vrstami iterabilnih podatkov.