Fonctions de l'itérateur
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.
L'installation :
composer require nette/utils
Tous les exemples supposent que l'alias suivant a été créé :
use Nette\Utils\Iterables;
contains (iterable $iterable, $value): bool
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.
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
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.
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 pour signature function ($value, $key, iterable $iterable): bool et doit renvoyer
true pour chaque élément pour que la méthode every() renvoie 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 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
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.
$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
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é.
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
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é.
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 pour 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 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
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.
$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
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.
$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
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.
$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().
toIterator (iterable $iterable): Iterator
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.
$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.
