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 crearea unui 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ă atunci când trebuie să determinați rapid dacă o anumită valoare se află în iterator, fără a fi nevoie să parcurgeți 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 îndeplinesc condiția definită în $predicate. Funcția $predicate are semnătura function ($value, $key, iterable $iterable): bool și trebuie să returneze true pentru fiecare element pentru ca metoda every() să returneze true.

$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 verifica dacă toate elementele dintr-o colecție îndeplinesc o anumită condiție, de exemplu, dacă toate numerele sunt mai mici decât o anumită valoare.

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, ceea ce înseamnă că transformarea 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.

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

La fel ca map(), această metodă utilizează un generator pentru procesare treptată și gestionare eficientă a memoriei. Acest lucru permite lucrul cu colecții mari și economisirea puterii de calcul în cazul parcurgerii parțiale a rezultatului.

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 = /* data 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 parcurgerea repetată ar fi costisitoare (de exemplu, la citirea datelor dintr-o bază 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, de exemplu, dacă colecția conține cel puțin un număr par.

Vezi every().

toIterator (iterable $iterable): Iterator

Convertește orice obiect iterabil (array, Traversable) într-un Iterator. Dacă intrarea 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 trebuie să vă asigurați că aveți la dispoziție un Iterator, indiferent de tipul datelor de intrare. Acest lucru poate fi util la crearea funcțiilor care lucrează cu diferite tipuri de date iterabile.