Lucrul cu iteratorii

Nette\Utils\Iterables este o clasă statică cu funcții pentru lucrul cu iteratorii. Echivalentul său pentru array-uri este Nette\Utils\Arrays.

Instalare:

composer require nette/utils

Toate exemplele presupun că a fost creat un alias:

use Nette\Utils\Iterables;

contains (iterable $iterable, $value): bool

Caută valoarea specificată în iterator. Utilizează comparație strictă (===) pentru a verifica potrivirea. Returnează true dacă valoarea este găsită, altfel false.

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

Această metodă este utilă pentru a determina rapid dacă o anumită valoare se află în iterator, fără a parcurge manual toate elementele.

containsKey (iterable $iterable, $key): bool

Caută cheia specificată în iterator. Utilizează comparație strictă (===) pentru a verifica potrivirea. Returnează true dacă cheia este găsită, altfel 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

Verifică dacă toate elementele iteratorului $iterable satisfac condiția definită în $predicate. Funcția $predicate are semnătura function ($value, $key, iterable $iterable): bool. Metoda returnează true doar dacă $predicate returnează true pentru fiecare element.

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

Această metodă este utilă pentru a valida dacă toate elementele dintr-o colecție îndeplinesc o anumită condiție.

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

Creează un nou iterator care conține doar acele elemente din iteratorul original care îndeplinesc condiția definită în $predicate. Funcția $predicate are semnătura function ($value, $key, iterable $iterable): bool și trebuie să returneze true pentru elementele care trebuie păstrate.

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

Metoda utilizează un generator, ceea ce înseamnă că filtrarea are loc treptat pe măsură ce rezultatul este parcurs. Acest lucru este eficient din punct de vedere al memoriei și permite procesarea colecțiilor very large. Dacă nu parcurgeți toate elementele iteratorului rezultat, veți economisi putere de calcul, deoarece nu toate elementele iteratorului original vor fi procesate.

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

Returnează primul element al iteratorului. Dacă este specificat $predicate, returnează primul element care îndeplinește condiția dată. Funcția $predicate are semnătura function ($value, $key, iterable $iterable): bool. Dacă nu se găsește niciun element corespunzător, se apelează funcția $else (dacă este specificată) și se returnează rezultatul acesteia. Dacă $else nu este specificat, se returnează 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

Această metodă este utilă atunci când trebuie să obțineți rapid primul element al unei colecții sau primul element care îndeplinește o anumită condiție, fără a fi nevoie să parcurgeți manual întreaga colecție.

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

Returnează cheia primului element al iteratorului. Dacă este specificat $predicate, returnează cheia primului element care îndeplinește condiția dată. Funcția $predicate are semnătura function ($value, $key, iterable $iterable): bool. Dacă nu se găsește niciun element corespunzător, se apelează funcția $else (dacă este specificată) și se returnează rezultatul acesteia. Dacă $else nu este specificat, se returnează 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

Creează un nou iterator prin aplicarea funcției $transformer fiecărui element al iteratorului original. Funcția $transformer are semnătura function ($value, $key, iterable $iterable): mixed, iar valoarea sa returnată este utilizată ca nouă valoare a elementului.

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

Metoda utilizează un generator, asigurând o transformare treptată (lazy) și eficientă din punct de vedere al memoriei. Permite procesarea colecțiilor mari și economisește resurse dacă nu se iterează peste toate elementele rezultatului.

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

Creează un nou iterator prin transformarea valorilor și cheilor iteratorului original. Funcția $transformer are semnătura function ($value, $key, iterable $iterable): ?array{$newKey, $newValue}. Dacă $transformer returnează null, elementul este omis. Pentru elementele păstrate, primul element al array-ului returnat este utilizat ca nouă cheie, iar al doilea element ca nouă valoare.

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

Similar cu map(), această metodă utilizează un generator pentru procesare treptată și eficientă din punct de vedere al memoriei.

memoize (iterable $iterable): IteratorAggregate

Creează un wrapper în jurul iteratorului care memorează în cache cheile și valorile sale în timpul iterației. Acest lucru permite iterația repetată a datelor fără a fi nevoie să parcurgeți din nou sursa originală de date.

$iterator = /* date care nu pot fi iterate de mai multe ori */
$memoized = Iterables::memoize($iterator);
// Acum puteți itera $memoized de mai multe ori fără pierderea datelor

Această metodă este utilă în situațiile în care trebuie să parcurgeți același set de date de mai multe ori, dar iteratorul original nu permite iterația repetată sau aceasta ar fi ineficientă (ex. citirea din baza de date sau fișier).

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

Verifică dacă cel puțin un element al iteratorului îndeplinește condiția definită în $predicate. Funcția $predicate are semnătura function ($value, $key, iterable $iterable): bool și trebuie să returneze true pentru cel puțin un element pentru ca metoda some() să returneze true.

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

Această metodă este utilă pentru a verifica rapid dacă există cel puțin un element într-o colecție care îndeplinește o anumită condiție.

Vezi și every().

toIterator (iterable $iterable): Iterator

Convertește orice obiect iterabil (array, Traversable) într-un Iterator. Dacă intrarea $iterable este deja un Iterator, o returnează neschimbată.

$array = [1, 2, 3];
$iterator = Iterables::toIterator($array);
// Acum aveți un Iterator în loc de un array

Această metodă este utilă atunci când aveți nevoie să garantați că lucrați cu un Iterator, indiferent de tipul datelor de intrare iterabile.