wip

Author: dg

utils/cs/iterables.texy

@@ -21,69 +21,85 @@ use Nette\Utils\Iterables;
 contains(iterable $iterable, $value): bool .[method]
 ----------------------------------------------------
 
-Testuje přítomnost hodnoty v iterátoru. Používá striktní porovnání (`===`).
+Tato metoda prochází zadaný iterátor a hledá, zda obsahuje konkrétní hodnotu. Používá striktní porovnání (`===`), což znamená, že porovnává nejen hodnotu, ale i datový typ. Je to užitečné, když potřebujete zjistit, zda se určitý prvek nachází v kolekci dat.
 
 ```php
 Iterables::contains(new ArrayIterator([1, 2, 3]), 1);    // true
 Iterables::contains(new ArrayIterator([1, 2, 3]), '1');  // false
 ```
 
+V druhém příkladu je výsledek false, protože '1' je řetězec, zatímco v iterátoru je číslo 1.
+
 
 containsKey(iterable $iterable, $value): bool .[method]
 -------------------------------------------------------
 
-Testuje přítomnost klíče v iterátoru. Používá striktní porovnání (`===`).
+Podobně jako metoda `contains()`, ale tato metoda hledá konkrétní klíč v iterátoru, ne hodnotu. Opět používá striktní porovnání (`===`). To je užitečné, když potřebujete zjistit, zda v kolekci existuje konkrétní index nebo klíč.
 
 ```php
 Iterables::containsKey(new ArrayIterator([1, 2, 3]), 0);  // true
 Iterables::containsKey(new ArrayIterator([1, 2, 3]), 4);  // false
 ```
 
+V prvním příkladu je výsledek true, protože 0 je platný index v iterátoru. V druhém příkladu je výsledek false, protože index 4 neexistuje.
+
 
 every(iterable $iterable, callable $predicate): bool .[method]
 --------------------------------------------------------------
 
-Testuje, zda všechny prvky iterátoru projdou testem implementovaným v `$predicate` se signaturou `function ($value, $key, iterable $iterable): bool`.
+Tato metoda testuje, zda všechny prvky v iterátoru splňují podmínku definovanou v funkci `$predicate`. Funkce `$predicate` se volá pro každý prvek a musí vracet true nebo false. Pokud funkce vrátí false pro jakýkoliv prvek, metoda `every()` okamžitě vrátí false. Pokud funkce vrátí true pro všechny prvky, metoda vrátí true.
 
 ```php
 $iterator = new ArrayIterator([1, 30, 39, 29, 10, 13]);
 $isBelowThreshold = fn($value) => $value < 40;
 $res = Iterables::every($iterator, $isBelowThreshold); // true
 ```
 
-Viz [#some()].
+V tomto příkladu funkce kontroluje, zda jsou všechna čísla menší než 40.
 
 
 filter(iterable $iterable, callable $predicate): Generator .[method]
 --------------------------------------------------------------------
 
-Iterátor, který filtruje prvky dle predikátu. Ten má signaturu `function ($value, $key, iterable $iterable): bool`. Zachovává původní klíče.
+Tato metoda vytváří nový iterátor, který obsahuje pouze ty prvky z původního iterátoru, pro které funkce `$predicate` vrátí true. Původní klíče jsou zachovány.
+
+Důležité je, že tato metoda vrací generátor. To znamená, že filtrování se provádí "líně" (lazy evaluation) - až ve chvíli, kdy se skutečně přistupuje k prvkům. To má několik výhod:
+
+1. Úspora paměti: Nemusíme držet v paměti celou filtrovanou kolekci najednou.
+2. Možnost práce s nekonečnými sekvencemi: Můžeme filtrovat i potenciálně nekonečné datové proudy.
+3. Efektivita: Pokud neprojdeme všechny prvky (např. když hledáme jen první vyhovující), ušetříme výpočetní čas.
 
 ```php
-$iterator = new ArrayIterator([1, 2, 3]);
-$iterator = Iterables::filter($iterator, fn($v) => $v < 3);
-// 1, 2
+$iterator = new ArrayIterator([1, 2, 3, 4, 5]);
+$evenNumbers = Iterables::filter($iterator, fn($v) => $v % 2 === 0);
+foreach ($evenNumbers as $number) {
+    echo $number . ' ';
+    if ($number > 3) break;
+}
+// Vypíše: 2 4
+// Všimněte si, že 5 ani nebylo zkontrolováno díky využití generátoru
 ```
 
 
 first(iterable $iterable, ?callable $predicate=null, ?callable $else=null): mixed .[method]
 -------------------------------------------------------------------------------------------
 
-Vrátí první položku (odpovídající predikátu, je-li zadán). Pokud taková položka neexistuje, vrátí výsledek volání `$else` nebo null.
-Parametr `$predicate` má signaturu `function ($value, $key, iterable $iterable): bool`.
+Tato metoda vrací první prvek iterátoru. Pokud je zadána funkce `$predicate`, vrátí první prvek, pro který tato funkce vrátí true. Pokud žádný prvek nevyhovuje (nebo je iterátor prázdný), vrátí se výsledek volání funkce `$else`, nebo null, pokud `$else` není zadáno.
 
 ```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
+Iterables::first(new ArrayIterator([]), else: fn() => 'prázdné'); // 'prázdné'
 ```
 
+Tato metoda je užitečná, když potřebujete rychle získat první prvek splňující určitou podmínku, aniž byste museli procházet celou kolekci.
+
 
 firstKey(iterable $iterable, ?callable $predicate=null, ?callable $else=null): mixed .[method]
 ----------------------------------------------------------------------------------------------
 
-Vrátí klíč první položky (odpovídající predikátu, je-li zadán). Pokud taková položka neexistuje, vrátí výsledek volání `$else` nebo null. Predikát má signaturu `function ($value, $key, iterable $iterable): bool`.
+Podobná metodě `first()`, ale místo hodnoty prvku vrací jeho klíč. Opět můžete použít `$predicate` pro definici podmínky a `$else` pro alternativní návratovou hodnotu.
 
 ```php
 Iterables::firstKey(new ArrayIterator([1, 2, 3]));                   // 0
@@ -92,64 +108,119 @@ Iterables::firstKey(new ArrayIterator(['a' => 1, 'b' => 2]));        // 'a'
 Iterables::firstKey(new ArrayIterator([]));                          // null
 ```
 
+Tato metoda je užitečná, když potřebujete zjistit klíč prvního prvku splňujícího určitou podmínku.
+
+
+map(iterable $iterable, callable $transformer): Generator .[method]
+-------------------------------------------------------------------
 
-map(iterable $iterable, callable $transformer): array .[method]
----------------------------------------------------------------
+Tato metoda vytváří nový iterátor, kde každý prvek je výsledkem aplikace funkce `$transformer` na odpovídající prvek původního iterátoru. Původní klíče jsou zachovány.
 
-Iterátor, který transformuje hodnoty voláním `$transformer`. Ten má signaturu `function ($value, $key, iterable $iterable): bool`. Zachovává původní klíče.
+Podobně jako `filter()`, i tato metoda vrací generátor, což přináší stejné výhody:
+
+1. Úspora paměti: Transformace se provádí postupně, ne najednou pro celou kolekci.
+2. Možnost práce s potenciálně nekonečnými sekvencemi.
+3. Efektivita: Pokud neprojdeme všechny prvky, ušetříme výpočetní čas.
 
 ```php
 $iterator = new ArrayIterator([1, 2, 3]);
-$iterator = Iterables::map($iterator, fn($v) => $v * 2);
-// 2, 4, 6
+$doubled = Iterables::map($iterator, fn($v) => $v * 2);
+foreach ($doubled as $number) {
+    echo $number . ' ';
+    if ($number > 4) break;
+}
+// Vypíše: 2 4 6
+// Všimněte si, že transformace se provádí postupně při iteraci
 ```
 
 
 mapWithKeys(iterable $iterable, callable $transformer): Generator .[method]
 --------------------------------------------------------------------------
 
-Iterátor, který transformuje klíče a hodnoty voláním `$transformer`. Pokud funkce vrátí null, prvek je přeskočen. Transformer má signaturu `function ($value, $key, iterable $iterable): ?array{newValue, newKey}`.
+Tato metoda je podobná metodě `map()`, ale umožňuje transformovat jak hodnoty, tak klíče. Funkce `$transformer` by měla vracet pole se dvěma prvky: novou hodnotou a novým klíčem. Pokud funkce vrátí null, prvek bude přeskočen.
+
+Využití generátoru zde přináší stejné výhody jako u metod `filter()` a `map()`:
+
+1. Úspora paměti při práci s velkými kolekcemi.
+2. Možnost transformovat potenciálně nekonečné sekvence.
+3. Efektivita při částečném průchodu kolekcí.
 
 ```php
-$iterator = new ArrayIterator(['a' => 1, 'b' => 2]);
-$iterator = Iterables::mapWithKeys($iterator, fn($v, $k) => $v > 1 ? [$v * 2, strtoupper($k)] : null);
-// [4 => 'B']
+$iterator = new ArrayIterator(['a' => 1, 'b' => 2, 'c' => 3]);
+$transformed = Iterables::mapWithKeys($iterator, function($v, $k) {
+    if ($v > 1) {
+        return [$v * 2, strtoupper($k)];
+    }
+    return null; // Tento prvek bude přeskočen
+});
+foreach ($transformed as $key => $value) {
+    echo "$key: $value, ";
+}
+// Vypíše: B: 4, C: 6,
 ```
 
 
 memoize(iterable $iterable): IteratorAggregate .[method]
 --------------------------------------------------------
 
-Obalí iterátor a během iterace ukládá do mezipaměti jeho klíče a hodnoty. To umožňuje opakovanou iteraci dat.
+Tato metoda vytváří "memoizovanou" verzi iterátoru. To znamená, že při prvním průchodu iterátorem se všechny hodnoty a klíče uloží do paměti. Při dalších průchodech se pak používají tyto uložené hodnoty místo opakovaného procházení původního iterátoru.
+
+To je užitečné v situacích, kdy:
+1. Potřebujete projít stejnou kolekcí dat vícekrát.
+2. Původní iterátor je "jednorázový" (např. generátor, který lze projít pouze jednou).
+3. Získávání dat z původního iterátoru je časově náročné a chcete výsledky ukládat do mezipaměti.
 
 ```php
-$iterator = new ArrayIterator([1, 2, 3]);
-$memoized = Iterables::memoize($iterator);
-// Můžete nyní iterovat $memoized vícekrát bez ztráty dat
+$expensiveData = function() {
+    yield 1;
+    sleep(1); // Simulace časově náročné operace
+    yield 2;
+    sleep(1);
+    yield 3;
+};
+
+$memoized = Iterables::memoize($expensiveData());
+
+// První průchod (pomalý)
+foreach ($memoized as $value) echo $value . ' ';
+// Vypíše: 1 2 3 (s pauzami)
+
+// Druhý průchod (rychlý, používá uložená data)
+foreach ($memoized as $value) echo $value . ' ';
+// Vypíše: 1 2 3 (okamžitě)
 ```
 
 
 some(iterable $iterable, callable $predicate): bool .[method]
 -------------------------------------------------------------
 
-Testuje, zda alespoň jeden prvek iterátoru projde testem implementovaným v `$predicate` se signaturou `function ($value, $key, iterable $iterable): bool`.
+Tato metoda testuje, zda alespoň jeden prvek iterátoru splňuje podmínku definovanou v funkci `$predicate`. Funkce `$predicate` se volá pro každý prvek a musí vracet true nebo false. Pokud funkce vrátí true pro jakýkoliv prvek, metoda `some()` okamžitě vrátí true. Pokud funkce vrátí false pro všechny prvky, metoda vrátí false.
 
 ```php
 $iterator = new ArrayIterator([1, 30, 39, 29, 10, 13]);
 $isEven = fn($value) => $value % 2 === 0;
 $res = Iterables::some($iterator, $isEven); // true
 ```
 
+V tomto příkladu funkce kontroluje, zda existuje alespoň jedno sudé číslo v kolekci.
+
 
 toIterator(iterable $iterable): Iterator .[method]
 --------------------------------------------------
 
-Vytvoří Iterator z čehokoliv, co je iterovatelné.
+Tato metoda konvertuje jakýkoliv iterovatelný objekt (pole, Iterator, IteratorAggregate) na objekt typu Iterator. To je užitečné, když potřebujete zajistit jednotné rozhraní pro práci s různými typy kolekcí.
 
 ```php
 $array = [1, 2, 3];
 $iterator = Iterables::toIterator($array);
 // Nyní máte Iterator místo pole
+
+foreach ($iterator as $value) {
+    echo $value . ' ';
+}
+// Vypíše: 1 2 3
 ```
 
+Tato metoda je zvláště užitečná, když píšete funkci, která má pracovat s iterátory, ale chcete umožnit uživatelům předávat i běžná pole.
+
 Viz [#every()].