Travailler avec les itérateurs
Nette\Utils\Iterables est une classe statique avec des fonctions pour travailler avec les itérateurs. Son équivalent pour les tableaux est Nette\Utils\Arrays.
Installation :
composer require nette/utils
Tous les exemples supposent qu'un alias a été créé :
use Nette\Utils\Iterables;
contains (iterable $iterable, $value): bool
Recherche la valeur spécifiée dans l'itérateur. Utilise une comparaison stricte (===) pour vérifier la
correspondance. Retourne true si la valeur est trouvée, sinon false.
Iterables::contains(new ArrayIterator([1, 2, 3]), 1); // true
Iterables::contains(new ArrayIterator([1, 2, 3]), '1'); // false
Cette méthode est utile lorsque vous avez besoin de déterminer rapidement si une valeur spécifique se trouve dans l'itérateur, sans avoir à parcourir tous les éléments manuellement.
containsKey (iterable $iterable, $key): bool
Recherche la clé spécifiée dans l'itérateur. Utilise une comparaison stricte (===) pour vérifier la
correspondance. Retourne true si la clé est trouvée, sinon 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
Vérifie si tous les éléments de l'itérateur satisfont la condition définie dans $predicate. La fonction
$predicate a la signature function ($value, $key, iterable $iterable): bool et doit retourner
true pour chaque élément pour que la méthode every() retourne true.
$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 si tous les éléments d'une collection satisfont une certaine condition, par exemple si tous les nombres sont inférieurs à une certaine valeur.
filter (iterable $iterable, callable $predicate): Generator
Crée un nouvel itérateur qui contient seulement les éléments de l'itérateur original qui satisfont la condition définie
dans $predicate. La fonction $predicate a la signature
function ($value, $key, iterable $iterable): bool et doit retourner true pour les éléments qui doivent
être conservés.
$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 se déroule progressivement lors du parcours du résultat. C'est efficace en termes de mémoire et permet de traiter même de très grandes collections. Si vous ne parcourez pas tous les éléments de l'itérateur résultant, vous économisez de la puissance de calcul, car tous les éléments de l'itérateur original ne sont pas traités.
first (iterable $iterable, ?callable $predicate=null, ?callable $else=null): mixed
Retourne le premier élément de l'itérateur. Si $predicate est spécifié, retourne le premier élément qui
satisfait la condition donnée. La fonction $predicate a la signature
function ($value, $key, iterable $iterable): bool. Si aucun élément correspondant n'est trouvé, la fonction
$else est appelée (si elle est spécifiée) et son résultat est retourné. Si $else n'est pas
spécifié, null est retourné.
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 lorsque vous avez besoin d'obtenir rapidement le premier élément d'une collection ou le premier élément satisfaisant une certaine condition, sans avoir à parcourir toute la collection manuellement.
firstKey (iterable $iterable, ?callable $predicate=null, ?callable $else=null): mixed
Retourne la clé du premier élément de l'itérateur. Si $predicate est spécifié, retourne la clé du premier
élément qui satisfait la condition donnée. La fonction $predicate a la signature
function ($value, $key, iterable $iterable): bool. Si aucun élément correspondant n'est trouvé, la fonction
$else est appelée (si elle est spécifiée) et son résultat est retourné. Si $else n'est pas
spécifié, null est retourné.
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
Crée un nouvel itérateur en appliquant la fonction $transformer à chaque élément de l'itérateur original. La
fonction $transformer a la signature function ($value, $key, iterable $iterable): mixed et sa valeur de
retour est utilisée comme nouvelle valeur de l'élément.
$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 déroule progressivement lors du parcours du résultat. C'est efficace en termes de mémoire et permet de traiter même de très grandes collections. Si vous ne parcourez pas tous les éléments de l'itérateur résultant, vous économisez de la puissance de calcul, car tous les éléments de l'itérateur original ne sont pas traités.
mapWithKeys (iterable $iterable, callable $transformer): Generator
Crée un nouvel itérateur par transformation des valeurs et des clés de l'itérateur original. La fonction
$transformer a la signature function ($value, $key, iterable $iterable): ?array{$newKey, $newValue}. Si
$transformer retourne null, l'élément est sauté. 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.
$iterator = new ArrayIterator(['a' => 1, 'b' => 2]);
$iterator = Iterables::mapWithKeys($iterator, fn($v, $k) => $v > 1 ? [$v * 2, strtoupper($k)] : null);
// [4 => 'B']
Tout comme map(), cette méthode utilise un générateur pour un traitement progressif et un travail efficace avec
la mémoire. Cela permet de travailler avec de grandes collections et d'économiser de la puissance de calcul lors d'un parcours
partiel du résultat.
memoize (iterable $iterable): IteratorAggregate
Crée un wrapper autour de l'itérateur qui, pendant l'itération, met en cache ses clés et valeurs. Cela permet une itération répétée des données sans nécessité de reparcourir la source de données originale.
$iterator = /* data, která nelze iterovat vícekrát */
$memoized = Iterables::memoize($iterator);
// Nyní můžete iterovat $memoized vícekrát bez ztráty dat
Cette méthode est utile dans des situations où vous avez besoin de parcourir plusieurs fois le même ensemble de données, mais l'itérateur original ne permet pas l'itération répétée ou un parcours répété serait coûteux (par ex. lors de la lecture de données depuis une base de données ou un fichier).
some (iterable $iterable, callable $predicate): bool
Vérifie si au moins un élément de l'itérateur satisfait la condition définie dans $predicate. La fonction
$predicate a la 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.
$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 une vérification rapide si dans la collection existe au moins un élément satisfaisant une certaine condition, par exemple si la collection contient au moins un nombre pair.
Voir every().
toIterator (iterable $iterable): Iterator
Convertit n'importe quel objet itérable (array, Traversable) en Iterator. Si l'entrée est déjà un Iterator, le retourne sans modification.
$array = [1, 2, 3];
$iterator = Iterables::toIterator($array);
// Nyní máte Iterator místo pole
Cette méthode est utile lorsque vous avez besoin d'assurer que vous disposez d'un Iterator, quel que soit le type de données d'entrée. Cela peut être utile lors de la création de fonctions qui travaillent avec différents types de données itérables.
