nette/utils 4.0.5

Author: dg

utils/cs/@home.texy

@@ -35,7 +35,7 @@ composer require nette/utils
 
 | verze     | kompatibilní s PHP
 |-----------|-------------------
-| Nette Utils 4.0 | PHP 8.0 – 8.3
+| Nette Utils 4.0 | PHP 8.0 – 8.4
 | Nette Utils 3.2 | PHP 7.2 – 8.3
 | Nette Utils 3.0 – 3.1 | PHP 7.1 – 8.0
 | Nette Utils 2.5 | PHP 5.6 – 8.0

utils/cs/arrays.texy

@@ -310,6 +310,29 @@ $res = Arrays::map($array, fn($value) => $value . $value);
 ```
 
 
+mapWithKeys(array $array, callable $transformer): array .[method]
+-----------------------------------------------------------------
+
+Tato metoda vytváří nové pole, kde jsou klíče a hodnoty transformovány pomocí zadané funkce `$transformer`. Funkce se aplikuje na každý prvek původního pole a vrací pole se dvěma prvky: nový klíč a nová hodnota. Pokud funkce vrátí null, daný prvek bude z výsledného pole vynechán.
+Callback má signaturu `function ($value, $key, array $array): ?array{$newKey, $newValue}`.
+
+```php
+$array = ['a' => 1, 'b' => 2, 'c' => 3];
+$result = Arrays::mapWithKeys($array, function($value, $key) {
+    if ($value % 2 === 0) {
+        return [strtoupper($key), $value * 10];
+    }
+    return null; // Lichá čísla budou přeskočena
+});
+// $result je ['B' => 20]
+```
+
+Tato metoda je užitečná v situacích, kdy potřebujete
+1. Změnit strukturu pole (klíče i hodnoty současně)
+2. Filtrovat prvky při transformaci (vracením null pro nežádoucí prvky)
+3. Vytvořit nové asociativní pole založené na původních datech
+
+
 mergeTree(array $array1, array $array2): array .[method]
 --------------------------------------------------------
 

utils/cs/iterables.texy

@@ -21,18 +21,20 @@ use Nette\Utils\Iterables;
 contains(iterable $iterable, $value): bool .[method]
 ----------------------------------------------------
 
-Testuje přítomnost hodnoty v iterátoru. Používá striktní porovnání (`===`).
+Hledá zadanou hodnotu v iterátoru. Používá striktní porovnání (`===`) pro ověření shody. Vrací `true`, pokud je hodnota nalezena, jinak `false`.
 
 ```php
 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, $value): bool .[method]
--------------------------------------------------------
 
-Testuje přítomnost klíče v iterátoru. Používá striktní porovnání (`===`).
+containsKey(iterable $iterable, $key): bool .[method]
+-----------------------------------------------------
+
+Hledá zadaný klíč v iterátoru. Používá striktní porovnání (`===`) pro ověření shody. Vrací `true`, pokud je klíč nalezen, jinak `false`.
 
 ```php
 Iterables::containsKey(new ArrayIterator([1, 2, 3]), 0);  // true
@@ -43,34 +45,35 @@ Iterables::containsKey(new ArrayIterator([1, 2, 3]), 4);  // false
 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`.
+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`.
 
 ```php
 $iterator = new ArrayIterator([1, 30, 39, 29, 10, 13]);
 $isBelowThreshold = fn($value) => $value < 40;
 $res = Iterables::every($iterator, $isBelowThreshold); // true
 ```
 
-Viz [#some()].
+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 .[method]
 --------------------------------------------------------------------
 
-Iterátor, který filtruje prvky dle predikátu. Ten má signaturu `function ($value, $key, iterable $iterable): bool`. Zachovává původní klíče.
+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.
 
 ```php
 $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 .[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`.
+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`.
 
 ```php
 Iterables::first(new ArrayIterator([1, 2, 3]));                   // 1
@@ -79,11 +82,13 @@ 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 .[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`.
+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`.
 
 ```php
 Iterables::firstKey(new ArrayIterator([1, 2, 3]));                   // 0
@@ -93,27 +98,73 @@ Iterables::firstKey(new ArrayIterator([]));                          // null
 ```
 
 
-map(iterable $iterable, callable $transformer): array .[method]
----------------------------------------------------------------
+map(iterable $iterable, callable $transformer): Generator .[method]
+-------------------------------------------------------------------
 
-Iterátor, který transformuje hodnoty voláním `$transformer`. Ten má signaturu `function ($value, $key, iterable $iterable): bool`. Zachovává původní klíče.
+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.
 
 ```php
 $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 .[method]
+---------------------------------------------------------------------------
+
+Vytváří nový iterátor transformací hodnot a klíčů původního iterátoru. Funkce `$transformer` má signaturu `function ($value, $key, iterable $iterable): ?array{newValue, newKey}`. 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.
+
+```php
+$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 .[method]
+--------------------------------------------------------
+
+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.
+
+```php
+$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 .[method]
 -------------------------------------------------------------
 
-Testuje, zda alespoň jeden prvek iterátoru projde testem implementovaným v `$predicate` se signaturou `function ($value, $key, iterable $iterable): 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`.
 
 ```php
 $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 .[method]
+--------------------------------------------------
+
+Převádí jakýkoliv iterovatelný objekt (array, Traversable) na Iterator. Pokud je vstup již Iterator, vrátí ho beze změny.
+
+```php
+$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.

utils/cs/strings.texy

@@ -483,8 +483,8 @@ Strings::match('žlutý!', '~\w+(!+)?~', captureOffset: true, utf8: true);
 ```
 
 
-matchAll(string $subject, string $pattern, bool $captureOffset=false, int $offset=0, bool $unmatchedAsNull=false, bool $patternOrder=false, bool $utf8=false): array .[method]
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+matchAll(string $subject, string $pattern, bool $captureOffset=false, int $offset=0, bool $unmatchedAsNull=false, bool $patternOrder=false, bool $utf8=false, bool $lazy=false): array|Generator .[method]
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 
 Hledá v řetězci všechny výskyty odpovídající regulárnímu výrazu a vrátí pole polí s nalezeným výrazem a jednotlivými podvýrazy.
 
@@ -550,6 +550,16 @@ Strings::matchAll('žlutý kůň', '~\w+~', captureOffset: true, utf8: true);
 ] */
 ```
 
+Pokud `$lazy` je `true`, funkce vrací `Generator` místo pole, což přináší významné výkonnostní výhody při práci s velkými řetězci. Generátor umožňuje vyhledávat shody postupně, místo celého řetězce najednou. To umožňuje efektivně pracovat i s extrémně velkými vstupními texty. Navíc můžete kdykoliv přerušit zpracování, pokud najdete hledanou shodu, což šetří výpočetní čas.
+
+```php
+$matches = Strings::matchAll($largeText, '~\w+~', lazy: true);
+foreach ($matches as $match) {
+    echo "Nalezeno: $match[0]\n";
+    // Zpracování může být kdykoli přerušeno
+}
+```
+
 
 replace(string $subject, string|array $pattern, string|callable $replacement='', int $limit=-1, bool $captureOffset=false, bool $unmatchedAsNull=false, bool $utf8=false): string .[method]
 -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------