Práce s iterátory

Nette\Utils\Iterables je statická třída s funkcemi pro práci s iterátory. Její obdobou pro pole je Nette\Utils\Arrays.

Instalace:

composer require nette/utils

Všechny příklady předpokládají vytvořený alias:

use Nette\Utils\Iterables;

contains(iterable $iterable, $value): bool

Hledá zadanou hodnotu v iterátoru. Používá striktní porovnání (===) pro ověření shody. Vrací true, pokud je hodnota nalezena, jinak false.

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

Tato metoda je užitečná, když potřebujete rychle zjistit, zda se konkrétní hodnota v iterátoru nachází, aniž byste museli procházet všechny prvky ručně.

containsKey(iterable $iterable, $key): bool

Hledá zadaný klíč v iterátoru. Používá striktní porovnání (===) pro ověření shody. Vrací true, pokud je klíč nalezen, jinak 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

Ověřuje, zda všechny prvky iterátoru splňují podmínku definovanou v $predicate. Funkce $predicate má signaturu function ($value, $key, iterable $iterable): bool a musí vracet true pro každý prvek, aby metoda every() vrátila true.

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

Tato metoda je užitečná pro ověření, zda všechny prvky v kolekci splňují určitou podmínku, například zda jsou všechna čísla menší než určitá hodnota.

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

Vytváří nový iterátor, který obsahuje pouze ty prvky z původního iterátoru, které splňují podmínku definovanou v $predicate. Funkce $predicate má signaturu function ($value, $key, iterable $iterable): bool a musí vracet true pro prvky, které mají být zachovány.

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

Metoda využívá generátor, což znamená, že filtrování probíhá postupně při procházení výsledku. To je efektivní z hlediska paměti a umožňuje zpracovávat i velmi velké kolekce. Pokud neprojdete všechny prvky výsledného iterátoru, ušetříte výpočetní výkon, protože se nezpracují všechny prvky původního iterátoru.

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

Vrací první prvek iterátoru. Pokud je zadán $predicate, vrací první prvek, který splňuje danou podmínku. Funkce $predicate má signaturu function ($value, $key, iterable $iterable): bool. Pokud není nalezen žádný vyhovující prvek, volá se funkce $else (pokud je zadána) a vrací se její výsledek. Pokud $else není zadáno, vrací se null.

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

Tato metoda je užitečná, když potřebujete rychle získat první prvek kolekce nebo první prvek splňující určitou podmínku, aniž byste museli procházet celou kolekci ručně.

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

Vrací klíč prvního prvku iterátoru. Pokud je zadán $predicate, vrací klíč prvního prvku, který splňuje danou podmínku. Funkce $predicate má signaturu function ($value, $key, iterable $iterable): bool. Pokud není nalezen žádný vyhovující prvek, volá se funkce $else (pokud je zadána) a vrací se její výsledek. Pokud $else není zadáno, vrací se null.

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

Vytváří nový iterátor aplikováním funkce $transformer na každý prvek původního iterátoru. Funkce $transformer má signaturu function ($value, $key, iterable $iterable): mixed a její návratová hodnota se použije jako nová hodnota prvku.

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

Metoda využívá generátor, což znamená, že transformace probíhá postupně při procházení výsledku. To je efektivní z hlediska paměti a umožňuje zpracovávat i velmi velké kolekce. Pokud neprojdete všechny prvky výsledného iterátoru, ušetříte výpočetní výkon, protože se nezpracují všechny prvky původního iterátoru.

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

Vytváří nový iterátor transformací hodnot a klíčů původního iterátoru. Funkce $transformer má signaturu function ($value, $key, iterable $iterable): ?array{$newKey, $newValue}. Pokud $transformer vrátí null, prvek je přeskočen. Pro zachované prvky se první prvek vráceného pole použije jako nový klíč a druhý prvek jako nová hodnota.

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

Stejně jako map(), tato metoda využívá generátor pro postupné zpracování a efektivní práci s pamětí. To umožňuje pracovat s velkými kolekcemi a šetřit výpočetní výkon při částečném průchodu výsledkem.

memoize(iterable $iterable): IteratorAggregate

Vytváří obal kolem iterátoru, který během iterace ukládá do mezipaměti jeho klíče a hodnoty. To umožňuje opakovanou iteraci dat bez nutnosti znovu procházet původní zdroj dat.

$iterator = /* data, která nelze iterovat vícekrát */
$memoized = Iterables::memoize($iterator);
// Nyní můžete iterovat $memoized vícekrát bez ztráty dat

Tato metoda je užitečná v situacích, kdy potřebujete vícekrát projít stejnou sadu dat, ale původní iterátor neumožňuje opakovanou iteraci nebo by opakované procházení bylo nákladné (např. při čtení dat z databáze nebo souboru).

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

Ověřuje, zda alespoň jeden prvek iterátoru splňuje podmínku definovanou v $predicate. Funkce $predicate má signaturu function ($value, $key, iterable $iterable): bool a musí vracet true pro alespoň jeden prvek, aby metoda some() vrátila true.

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

Tato metoda je užitečná pro rychlé ověření, zda v kolekci existuje alespoň jeden prvek splňující určitou podmínku, například zda kolekce obsahuje alespoň jedno sudé číslo.

Viz every().

toIterator(iterable $iterable): Iterator

Převádí jakýkoliv iterovatelný objekt (array, Traversable) na Iterator. Pokud je vstup již Iterator, vrátí ho beze změny.

$array = [1, 2, 3];
$iterator = Iterables::toIterator($array);
// Nyní máte Iterator místo pole

Tato metoda je užitečná, když potřebujete zajistit, že máte k dispozici Iterator, bez ohledu na typ vstupních dat. To může být užitečné při vytváření funkcí, které pracují s různými typy iterovatelných dat.