Lavorare con gli iteratori

Nette\Utils\Iterables è una classe statica con funzioni per lavorare con gli iteratori. La sua controparte per gli array è Nette\Utils\Arrays.

Installazione:

composer require nette/utils

Tutti gli esempi presuppongono la creazione di un alias:

use Nette\Utils\Iterables;

contains (iterable $iterable, $value): bool

Cerca il valore specificato nell'iteratore. Utilizza un confronto rigoroso (===) per verificare la corrispondenza. Restituisce true se il valore viene trovato, altrimenti false.

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

Questo metodo è utile quando è necessario determinare rapidamente se un valore specifico si trova nell'iteratore senza dover scorrere manualmente tutti gli elementi.

containsKey (iterable $iterable, $key): bool

Cerca la chiave specificata nell'iteratore. Utilizza un confronto rigoroso (===) per verificare la corrispondenza. Restituisce true se la chiave viene trovata, altrimenti 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

Verifica se tutti gli elementi dell'iteratore soddisfano la condizione definita in $predicate. La funzione $predicate ha la firma function ($value, $key, iterable $iterable): bool e deve restituire true per ogni elemento affinché il metodo every() restituisca true.

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

Questo metodo è utile per verificare se tutti gli elementi di una collezione soddisfano una determinata condizione, ad esempio se tutti i numeri sono inferiori a un certo valore.

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

Crea un nuovo iteratore che contiene solo gli elementi dell'iteratore originale che soddisfano la condizione definita in $predicate. La funzione $predicate ha la firma function ($value, $key, iterable $iterable): bool e deve restituire true per gli elementi che devono essere conservati.

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

Il metodo utilizza un generatore, il che significa che il filtraggio avviene gradualmente durante l'attraversamento del risultato. Questo è efficiente dal punto di vista della memoria e consente di elaborare anche collezioni molto grandi. Se non si attraversano tutti gli elementi dell'iteratore risultante, si risparmia potenza di calcolo, poiché non vengono elaborati tutti gli elementi dell'iteratore originale.

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

Restituisce il primo elemento dell'iteratore. Se viene specificato $predicate, restituisce il primo elemento che soddisfa la condizione data. La funzione $predicate ha la firma function ($value, $key, iterable $iterable): bool. Se non viene trovato alcun elemento corrispondente, viene chiamata la funzione $else (se specificata) e viene restituito il suo risultato. Se $else non è specificato, viene restituito 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

Questo metodo è utile quando è necessario ottenere rapidamente il primo elemento di una collezione o il primo elemento che soddisfa una determinata condizione, senza dover attraversare manualmente l'intera collezione.

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

Restituisce la chiave del primo elemento dell'iteratore. Se viene specificato $predicate, restituisce la chiave del primo elemento che soddisfa la condizione data. La funzione $predicate ha la firma function ($value, $key, iterable $iterable): bool. Se non viene trovato alcun elemento corrispondente, viene chiamata la funzione $else (se specificata) e viene restituito il suo risultato. Se $else non è specificato, viene restituito 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

Crea un nuovo iteratore applicando la funzione $transformer a ogni elemento dell'iteratore originale. La funzione $transformer ha la firma function ($value, $key, iterable $iterable): mixed e il suo valore di ritorno viene utilizzato come nuovo valore dell'elemento.

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

Il metodo utilizza un generatore, il che significa che la trasformazione avviene gradualmente durante l'attraversamento del risultato. Questo è efficiente dal punto di vista della memoria e consente di elaborare anche collezioni molto grandi. Se non si attraversano tutti gli elementi dell'iteratore risultante, si risparmia potenza di calcolo, poiché non vengono elaborati tutti gli elementi dell'iteratore originale.

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

Crea un nuovo iteratore trasformando i valori e le chiavi dell'iteratore originale. La funzione $transformer ha la firma function ($value, $key, iterable $iterable): ?array{$newKey, $newValue}. Se $transformer restituisce null, l'elemento viene saltato. Per gli elementi conservati, il primo elemento dell'array restituito viene utilizzato come nuova chiave e il secondo elemento come nuovo valore.

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

Come map(), questo metodo utilizza un generatore per l'elaborazione graduale e un lavoro efficiente con la memoria. Ciò consente di lavorare con grandi collezioni e risparmiare potenza di calcolo durante l'attraversamento parziale del risultato.

memoize (iterable $iterable): IteratorAggregate

Crea un wrapper attorno all'iteratore che memorizza nella cache le sue chiavi e i suoi valori durante l'iterazione. Ciò consente l'iterazione ripetuta dei dati senza la necessità di attraversare nuovamente l'origine dati originale.

$iterator = /* dati che non possono essere iterati più volte */
$memoized = Iterables::memoize($iterator);
// Ora puoi iterare $memoized più volte senza perdita di dati

Questo metodo è utile in situazioni in cui è necessario attraversare più volte lo stesso set di dati, ma l'iteratore originale non consente l'iterazione ripetuta o l'attraversamento ripetuto sarebbe costoso (ad esempio, durante la lettura di dati da un database o da un file).

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

Verifica se almeno un elemento dell'iteratore soddisfa la condizione definita in $predicate. La funzione $predicate ha la firma function ($value, $key, iterable $iterable): bool e deve restituire true per almeno un elemento affinché il metodo some() restituisca true.

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

Questo metodo è utile per verificare rapidamente se esiste almeno un elemento nella collezione che soddisfa una determinata condizione, ad esempio se la collezione contiene almeno un numero pari.

Vedi #every().

toIterator (iterable $iterable): Iterator

Converte qualsiasi oggetto iterabile (array, Traversable) in un Iterator. Se l'input è già un Iterator, lo restituisce senza modifiche.

$array = [1, 2, 3];
$iterator = Iterables::toIterator($array);
// Ora hai un Iterator invece di un array

Questo metodo è utile quando è necessario assicurarsi di avere a disposizione un Iterator, indipendentemente dal tipo di dati di input. Questo può essere utile durante la creazione di funzioni che lavorano con diversi tipi di dati iterabili.