Funzioni di iteratore

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

Installazione:

composer require nette/utils

Tutti gli esempi presuppongono la creazione del seguente alias:

use Nette\Utils\Iterables;

contains (iterable $iterable, $value): bool

Cerca un valore dato in un 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 è presente in un iteratore, senza iterare manualmente tutti gli elementi.

containsKey (iterable $iterable, $key): bool

Cerca una determinata chiave in un 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 che tutti gli elementi di un insieme soddisfino una certa condizione, ad esempio se tutti i numeri sono inferiori a un valore specifico.

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

$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 in modo incrementale durante l'iterazione. Questo metodo è efficiente dal punto di vista della memoria e consente di gestire raccolte molto grandi. Se non si iterano tutti gli elementi dell'iteratore risultante, si risparmia in termini 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 fornito $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 richiamata la funzione $else (se fornita) e viene restituito il suo risultato. Se $else non è fornito, 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 recuperare rapidamente il primo elemento di un insieme o il primo elemento che soddisfa una determinata condizione, senza dover iterare manualmente l'intero insieme.

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

Restituisce la chiave del primo elemento dell'iteratore. Se viene fornito $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 richiamata la funzione $else (se fornita) e viene restituito il suo risultato. Se $else non viene fornito, 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 in modo incrementale durante l'iterazione. Questo metodo è efficiente dal punto di vista della memoria e consente di gestire collezioni molto grandi. Se non si iterano tutti gli elementi dell'iteratore risultante, si risparmia in termini 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 mantenuti, 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 incrementale e l'efficienza della memoria. In questo modo è possibile lavorare con collezioni di grandi dimensioni e risparmiare sullo sforzo computazionale elaborando solo una parte del risultato.

memoize (iterable $iterable): IteratorAggregate

Crea un wrapper attorno a un iteratore che memorizza nella cache le chiavi e i valori durante l'iterazione. Ciò consente di ripetere l'iterazione dei dati senza dover rielaborare la fonte di dati originale.

$iterator = /* data that cannot be iterated multiple times */
$memoized = Iterables::memoize($iterator);
// Now you can iterate $memoized multiple times without data loss

Questo metodo è utile nelle situazioni in cui è necessario iterare più volte sullo stesso insieme di dati, ma l'iteratore originale non supporta l'iterazione ripetuta o l'iterazione ripetuta sarebbe costosa (ad esempio, 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 in un insieme c'è almeno un elemento che soddisfa una certa condizione, ad esempio se l'insieme contiene almeno un numero pari.

Vedere every().

toIterator (iterable $iterable): Iterator

Converte qualsiasi oggetto iterabile (array, Traversable) in un iteratore. Se l'input è già un iteratore, viene restituito invariato.

$array = [1, 2, 3];
$iterator = Iterables::toIterator($array);
// Now you have an Iterator instead of an array

Questo metodo è utile quando è necessario assicurarsi di avere un Iteratore, indipendentemente dal tipo di dati in ingresso. Può essere utile quando si creano funzioni che lavorano con diversi tipi di dati iterabili.