Iterator-Funktionen
*******************

.[perex]{data-version:4.0.4}
[api: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 |arrays].


Installation:

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

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

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


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

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

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

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

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

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

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

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.

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

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.

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

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

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.

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

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.

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

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.

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

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.

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

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.

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


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

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

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