Iterator-Funktionen

Nette\Utils\Iterables ist eine statische Klasse mit Funktionen für die Arbeit mit Iteratoren. Ihr Gegenstück für Arrays ist Nette\Utils\Arrays.

Installation:

composer require nette/utils

Bei allen Beispielen wird davon ausgegangen, dass der folgende Alias erstellt wurde:

use Nette\Utils\Iterables;

contains (iterable $iterable, $value): bool

Sucht nach einem bestimmten Wert in einem Iterator. Verwendet einen strengen Vergleich (===), um nach einer Übereinstimmung zu suchen. Gibt true zurück, wenn der Wert gefunden wird, andernfalls false.

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

Diese Methode ist nützlich, wenn Sie schnell feststellen müssen, ob ein bestimmter Wert in einem Iterator vorhanden ist, ohne manuell durch alle Elemente zu iterieren.

containsKey (iterable $iterable, $key): bool

Sucht nach einem bestimmten Schlüssel in einem Iterator. Verwendet einen strikten Vergleich (===), um nach einer Übereinstimmung zu suchen. Gibt true zurück, wenn der Schlüssel gefunden wird, andernfalls 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

Überprüft, ob alle Elemente des Iterators die in $predicate definierte Bedingung erfüllen. Die Funktion $predicate hat die Signatur function ($value, $key, iterable $iterable): bool und muss für jedes Element true zurückgeben, damit die Methode every() true zurückgibt.

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

Diese Methode ist nützlich, um zu überprüfen, ob alle Elemente in einer Sammlung eine bestimmte Bedingung erfüllen, z. B. ob alle Zahlen unter einem bestimmten Wert liegen.

filter (iterable $iterable, callable $predicate): Generator

Erzeugt einen neuen Iterator, der nur die Elemente des ursprünglichen Iterators enthält, die die in $predicate definierte Bedingung erfüllen. Die Funktion $predicate hat die Signatur function ($value, $key, iterable $iterable): bool und muss für Elemente, die beibehalten werden sollen, true zurückgeben.

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

Die Methode verwendet einen Generator, was bedeutet, dass die Filterung während der Iteration inkrementell erfolgt. Dies ist speichereffizient und ermöglicht die Verarbeitung sehr großer Sammlungen. Wenn Sie nicht durch alle Elemente des resultierenden Iterators iterieren, sparen Sie Rechenaufwand, da nicht alle Elemente des ursprünglichen Iterators verarbeitet werden.

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

Gibt das erste Element des Iterators zurück. Wenn $predicate angegeben ist, wird das erste Element zurückgegeben, das die angegebene Bedingung erfüllt. Die Funktion $predicate hat die Signatur function ($value, $key, iterable $iterable): bool. Wenn kein übereinstimmendes Element gefunden wird, wird die Funktion $else (falls angegeben) aufgerufen und ihr Ergebnis zurückgegeben. Wenn $else nicht angegeben ist, wird null zurückgegeben.

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

Diese Methode ist nützlich, wenn Sie schnell das erste Element einer Sammlung oder das erste Element, das eine bestimmte Bedingung erfüllt, abrufen möchten, ohne die gesamte Sammlung manuell durchlaufen zu müssen.

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

Gibt den Schlüssel des ersten Elements des Iterators zurück. Wenn $predicate angegeben ist, wird der Schlüssel des ersten Elements zurückgegeben, das die angegebene Bedingung erfüllt. Die Funktion $predicate hat die Signatur function ($value, $key, iterable $iterable): bool. Wird kein passendes Element gefunden, wird die Funktion $else (falls angegeben) aufgerufen und ihr Ergebnis zurückgegeben. Wenn $else nicht angegeben ist, wird null zurückgegeben.

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

Erzeugt einen neuen Iterator durch Anwendung der Funktion $transformer auf jedes Element des ursprünglichen Iterators. Die Funktion $transformer hat die Signatur function ($value, $key, iterable $iterable): mixed und ihr Rückgabewert wird als neuer Wert des Elements verwendet.

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

Die Methode verwendet einen Generator, was bedeutet, dass die Umwandlung während der Iteration inkrementell erfolgt. Dies ist speichereffizient und ermöglicht den Umgang mit sehr großen Sammlungen. Wenn Sie nicht durch alle Elemente des resultierenden Iterators iterieren, sparen Sie Rechenaufwand, da nicht alle Elemente des ursprünglichen Iterators verarbeitet werden.

mapWithKeys (iterable $iterable, callable $transformer): Generator

Erzeugt einen neuen Iterator durch Umwandlung der Werte und Schlüssel des ursprünglichen Iterators. Die Funktion $transformer hat die Signatur function ($value, $key, iterable $iterable): ?array{$newKey, $newValue}. Wenn $transformer null zurückgibt, wird das Element übersprungen. Bei beibehaltenen Elementen wird das erste Element des zurückgegebenen Arrays als neuer Schlüssel und das zweite Element als neuer Wert verwendet.

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

Wie map() verwendet diese Methode einen Generator für inkrementelle Verarbeitung und Speichereffizienz. Dies ermöglicht die Arbeit mit großen Sammlungen und spart Rechenaufwand, indem nur ein Teil des Ergebnisses verarbeitet wird.

memoize (iterable $iterable): IteratorAggregate

Erzeugt einen Wrapper um einen Iterator, der seine Schlüssel und Werte während der Iteration zwischenspeichert. Dies ermöglicht eine wiederholte Iteration über die Daten, ohne dass die ursprüngliche Datenquelle erneut verarbeitet werden muss.

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

Diese Methode ist in Situationen nützlich, in denen Sie denselben Datensatz mehrmals durchlaufen müssen, der ursprüngliche Iterator jedoch keine wiederholte Iteration unterstützt oder eine wiederholte Iteration zu kostspielig wäre (z. B. beim Lesen von Daten aus einer Datenbank oder Datei).

some (iterable $iterable, callable $predicate): bool

Prüft, ob mindestens ein Element des Iterators die in $predicate definierte Bedingung erfüllt. Die Funktion $predicate hat die Signatur function ($value, $key, iterable $iterable): bool und muss für mindestens ein Element true zurückgeben, damit die Methode some() true zurückgibt.

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

Diese Methode ist nützlich, um schnell zu überprüfen, ob es mindestens ein Element in einer Sammlung gibt, das eine bestimmte Bedingung erfüllt, z. B. ob die Sammlung mindestens eine gerade Zahl enthält.

Siehe every().

toIterator (iterable $iterable): Iterator

Konvertiert ein beliebiges iterierbares Objekt (Array, Traversable) in einen Iterator. Wenn die Eingabe bereits ein Iterator ist, wird er unverändert zurückgegeben.

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

Diese Methode ist nützlich, wenn Sie sicherstellen müssen, dass Sie einen Iterator haben, unabhängig vom Typ der Eingabedaten. Dies kann bei der Erstellung von Funktionen nützlich sein, die mit verschiedenen Typen von Iterationsdaten arbeiten.