Funzioni di iteratore
*********************

.[perex]{data-version:4.0.4}
[api:Nette\Utils\Iterables] è una classe statica con funzioni per lavorare con gli iteratori. La sua controparte per gli array è [NetteUtilsArrays |arrays].


Installazione:

```shell
composer require nette/utils
```

Tutti gli esempi presuppongono la creazione del seguente alias:

```php
use Nette\Utils\Iterables;
```


contains(iterable $iterable, $value): bool .[method]
----------------------------------------------------

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

```php
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 .[method]
-----------------------------------------------------

Cerca una determinata chiave in un iteratore. Utilizza un confronto rigoroso (`===`) per verificare la corrispondenza. Restituisce `true` se la chiave viene trovata, altrimenti `false`.

```php
Iterables::containsKey(new ArrayIterator([1, 2, 3]), 0);  // true
Iterables::containsKey(new ArrayIterator([1, 2, 3]), 4);  // false
```


every(iterable $iterable, callable $predicate): bool .[method]
--------------------------------------------------------------

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

```php
$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 .[method]
--------------------------------------------------------------------

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.

```php
$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 .[method]
-------------------------------------------------------------------------------------------

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

```php
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 .[method]
----------------------------------------------------------------------------------------------

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

```php
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 .[method]
-------------------------------------------------------------------

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.

```php
$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 .[method]
---------------------------------------------------------------------------

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.

```php
$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 .[method]
--------------------------------------------------------

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.

```php
$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 .[method]
-------------------------------------------------------------

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

```php
$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() |#every()].


toIterator(iterable $iterable): Iterator .[method]
--------------------------------------------------

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

```php
$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.