Fonctions de l'itérateur
************************

.[perex]{data-version:4.0.4}
[api:Nette\Utils\Iterables] est une classe statique contenant des fonctions permettant de travailler avec des itérateurs. Son équivalent pour les tableaux est [Nette\Utils\Arrays |arrays].


L'installation :

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

Tous les exemples supposent que l'alias suivant a été créé :

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


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

Recherche une valeur donnée dans un itérateur. Utilise une comparaison stricte (`===`) pour vérifier la correspondance. Retourne `true` si la valeur est trouvée, sinon `false`.

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

Cette méthode est utile pour déterminer rapidement si une valeur spécifique est présente dans un itérateur sans avoir à parcourir manuellement tous les éléments.


containsKey(iterable $iterable, $key): bool .[method]
-----------------------------------------------------

Recherche une clé donnée dans un itérateur. Utilise une comparaison stricte (`===`) pour vérifier s'il y a une correspondance. Retourne `true` si la clé est trouvée, sinon `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]
--------------------------------------------------------------

Vérifie si tous les éléments de l'itérateur satisfont à la condition définie dans `$predicate`. La fonction `$predicate` a pour signature `function ($value, $key, iterable $iterable): bool` et doit renvoyer `true` pour chaque élément pour que la méthode `every()` renvoie `true`.

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

Cette méthode est utile pour vérifier que tous les éléments d'une collection remplissent une certaine condition, par exemple si tous les nombres sont inférieurs à une valeur spécifique.


filter(iterable $iterable, callable $predicate): Generator .[method]
--------------------------------------------------------------------

Crée un nouvel itérateur qui ne contient que les éléments de l'itérateur original qui satisfont à la condition définie dans `$predicate`. La fonction `$predicate` a pour signature `function ($value, $key, iterable $iterable): bool` et doit renvoyer `true` pour les éléments qui doivent être conservés.

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

La méthode utilise un générateur, ce qui signifie que le filtrage s'effectue de manière incrémentielle au cours de l'itération. Cette méthode est économe en mémoire et permet de traiter de très grandes collections. Si vous n'itérez pas sur tous les éléments de l'itérateur résultant, vous économisez des efforts de calcul puisque tous les éléments de l'itérateur d'origine ne sont pas traités.


first(iterable $iterable, ?callable $predicate=null, ?callable $else=null): mixed .[method]
-------------------------------------------------------------------------------------------

Renvoie le premier élément de l'itérateur. Si `$predicate` est fourni, il renvoie le premier élément qui satisfait à la condition donnée. La fonction `$predicate` a pour signature `function ($value, $key, iterable $iterable): bool`. Si aucun élément correspondant n'est trouvé, la fonction `$else` (si elle est fournie) est appelée et son résultat est renvoyé. Si `$else` n'est pas fourni, `null` est renvoyé.

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

Cette méthode est utile pour récupérer rapidement le premier élément d'une collection ou le premier élément qui répond à une certaine condition sans avoir à parcourir manuellement l'ensemble de la collection.


firstKey(iterable $iterable, ?callable $predicate=null, ?callable $else=null): mixed .[method]
----------------------------------------------------------------------------------------------

Renvoie la clé du premier élément de l'itérateur. Si `$predicate` est fourni, il renvoie la clé du premier élément qui satisfait à la condition donnée. La fonction `$predicate` a pour signature `function ($value, $key, iterable $iterable): bool`. Si aucun élément correspondant n'est trouvé, la fonction `$else` (si elle est fournie) est appelée et son résultat est renvoyé. Si `$else` n'est pas fourni, `null` est renvoyé.

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

Crée un nouvel itérateur en appliquant la fonction `$transformer` à chaque élément de l'itérateur original. La fonction `$transformer` a pour signature `function ($value, $key, iterable $iterable): mixed` et sa valeur de retour est utilisée comme nouvelle valeur de l'élément.

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

La méthode utilise un générateur, ce qui signifie que la transformation se produit de manière incrémentielle au cours de l'itération. Cela permet d'économiser de la mémoire et de traiter de très grandes collections. Si vous n'itérez pas sur tous les éléments de l'itérateur résultant, vous économisez des efforts de calcul puisque tous les éléments de l'itérateur d'origine ne sont pas traités.


mapWithKeys(iterable $iterable, callable $transformer): Generator .[method]
---------------------------------------------------------------------------

Crée un nouvel itérateur en transformant les valeurs et les clés de l'itérateur original. La fonction `$transformer` a pour signature `function ($value, $key, iterable $iterable): ?array{$newKey, $newValue}`. Si `$transformer` renvoie `null`, l'élément est ignoré. Pour les éléments conservés, le premier élément du tableau retourné est utilisé comme nouvelle clé et le deuxième élément comme nouvelle valeur.

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

Comme `map()`, cette méthode utilise un générateur pour le traitement incrémental et l'efficacité de la mémoire. Cela permet de travailler avec de grandes collections et d'économiser l'effort de calcul en ne traitant qu'une partie du résultat.


memoize(iterable $iterable): IteratorAggregate .[method]
--------------------------------------------------------

Crée une enveloppe autour d'un itérateur qui met en cache ses clés et ses valeurs pendant l'itération. Cela permet de répéter l'itération sur les données sans avoir à retraiter la source de données d'origine.

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

Cette méthode est utile dans les situations où vous devez itérer plusieurs fois sur le même ensemble de données, mais où l'itérateur original ne supporte pas l'itération répétée ou l'itération répétée serait coûteuse (par exemple, la lecture de données à partir d'une base de données ou d'un fichier).


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

Vérifie si au moins un élément de l'itérateur satisfait à la condition définie dans `$predicate`. La fonction `$predicate` a pour signature `function ($value, $key, iterable $iterable): bool` et doit retourner `true` pour au moins un élément pour que la méthode `some()` retourne `true`.

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

Cette méthode est utile pour vérifier rapidement si au moins un élément d'une collection remplit une certaine condition, par exemple si la collection contient au moins un nombre pair.

Voir [every() |#every()].


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

Convertit n'importe quel objet itérable (tableau, Traversable) en un Iterator. Si l'entrée est déjà un Iterator, elle est retournée inchangée.

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

Cette méthode est utile lorsque vous devez vous assurer que vous disposez d'un itérateur, quel que soit le type de données en entrée. Cela peut être utile lors de la création de fonctions qui fonctionnent avec différents types de données itérables.