nette/utils 4.0.5

utils/bg/@home.texy

@@ -35,7 +35,7 @@ composer require nette/utils
 
 | 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/bg/arrays.texy

@@ -310,6 +310,20 @@ $res = Arrays::map($array, fn($value) => $value . $value);
 ```
 
 
+mapWithKeys(array $array, callable $transformer): array .[method]
+-----------------------------------------------------------------
+
+Създава нов масив, като трансформира стойностите и ключовете на оригиналния масив. Функцията `$transformer` има сигнатура `function ($value, $key, array $array): ?array{$newValue, $newKey}`. Ако `$transformer` върне `null`, елементът се пропуска. За запазените елементи първият елемент от върнатия масив се използва като нов ключ, а вторият елемент - като нова стойност.
+
+```php
+$array = ['a' => 1, 'b' => 2, 'c' => 3];
+$result = Arrays::mapWithKeys($array, fn($v, $k) => $v > 1 ? [$v * 2, strtoupper($k)] : null);
+// [4 => 'B']
+```
+
+Този метод е полезен в ситуации, в които трябва да се промени структурата на масив (едновременно и ключове, и стойности) или да се филтрират елементите по време на преобразуването (чрез връщане на null за нежелани елементи).
+
+
 mergeTree(array $array1, array $array2): array .[method]
 --------------------------------------------------------
 

utils/bg/iterables.texy

@@ -11,7 +11,7 @@
 composer require nette/utils
 ```
 
-Всички примери предполагат създаването на псевдоним:
+Всички примери предполагат, че е създаден следният псевдоним:
 
 ```php
 use Nette\Utils\Iterables;
@@ -21,18 +21,20 @@ use Nette\Utils\Iterables;
 contains(iterable $iterable, $value): bool .[method]
 ----------------------------------------------------
 
-Тества за наличие на стойност в итератора. Използва стриктно сравнение (`===`).
+Търси дадена стойност в итератор. Използва стриктно сравнение (`===`), за да провери за съвпадение. Връща `true`, ако стойността е намерена, в противен случай `false`.
 
 ```php
 Iterables::contains(new ArrayIterator([1, 2, 3]), 1);    // true
 Iterables::contains(new ArrayIterator([1, 2, 3]), '1');  // false
 ```
 
+Този метод е полезен, когато трябва бързо да определите дали определена стойност присъства в итератора, без да преминавате ръчно през всички елементи.
 
-containsKey(iterable $iterable, $value): bool .[method]
--------------------------------------------------------
 
-Тества за наличие на ключ в итератора. Използва стриктно сравнение (`===`).
+containsKey(iterable $iterable, $key): bool .[method]
+-----------------------------------------------------
+
+Търси даден ключ в итератор. Използва стриктно сравнение (`===`), за да провери за съвпадение. Връща `true`, ако ключът е намерен, в противен случай `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]
 --------------------------------------------------------------
 
-Проверява дали всички елементи на итератора са преминали тест, реализиран в `$predicate` със сигнатура `function ($value, $key, iterable $iterable): bool`.
+Проверява дали всички елементи на итератора отговарят на условието, дефинирано в `$predicate`. Функцията `$predicate` има сигнатура `function ($value, $key, iterable $iterable): bool` и трябва да връща `true` за всеки елемент, за да може методът `every()` да връща `true`.
 
 ```php
 $iterator = new ArrayIterator([1, 30, 39, 29, 10, 13]);
 $isBelowThreshold = fn($value) => $value < 40;
 $res = Iterables::every($iterator, $isBelowThreshold); // true
 ```
 
-Вижте [some( |#some()]).
+Този метод е полезен за проверка дали всички елементи в дадена колекция отговарят на определено условие, например дали всички числа са под определена стойност.
 
 
 filter(iterable $iterable, callable $predicate): Generator .[method]
 --------------------------------------------------------------------
 
-Итератор, който филтрира елементите в съответствие с предикат. Предикатът има сигнатурата `function ($value, $key, iterable $iterable): bool`. Запазва оригиналните ключове.
+Създава нов итератор, който съдържа само елементите от оригиналния итератор, които отговарят на условието, дефинирано в `$predicate`. Функцията `$predicate` има сигнатура `function ($value, $key, iterable $iterable): bool` и трябва да връща `true` за елементите, които трябва да бъдат запазени.
 
 ```php
 $iterator = new ArrayIterator([1, 2, 3]);
 $iterator = Iterables::filter($iterator, fn($v) => $v < 3);
 // 1, 2
 ```
 
+Методът използва генератор, което означава, че филтрирането се извършва инкрементално по време на итерацията. Това е ефективно по отношение на паметта и позволява работа с много големи колекции. Ако не итерирате през всички елементи на получения итератор, спестявате изчислителни усилия, тъй като не всички елементи на първоначалния итератор се обработват.
+
 
 first(iterable $iterable, ?callable $predicate=null, ?callable $else=null): mixed .[method]
 -------------------------------------------------------------------------------------------
 
-Връща първия елемент (отговарящ на предиката, ако е зададен). Ако няма такъв елемент, се връща резултатът от извикването на `$else` или null.
-Параметърът `$predicate` има сигнатура `function ($value, $key, iterable $iterable): bool`.
+Връща първия елемент на итератора. Ако е предоставен `$predicate`, се връща първият елемент, който отговаря на даденото условие. Функцията `$predicate` има сигнатура `function ($value, $key, iterable $iterable): bool`. Ако не бъде намерен съответстващ елемент, се извиква функцията `$else` (ако е предоставена) и се връща нейният резултат. Ако не е предоставена `$else`, се връща `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
 ```
 
+Този метод е полезен, когато трябва бързо да се извлече първият елемент от дадена колекция или първият елемент, който отговаря на определено условие, без да се налага ръчно да се итерира цялата колекция.
+
 
 firstKey(iterable $iterable, ?callable $predicate=null, ?callable $else=null): mixed .[method]
 ----------------------------------------------------------------------------------------------
 
-Връща ключа на първия елемент (отговарящ на предиката, ако е зададен). Ако няма такъв елемент, се връща резултатът от извикването на `$else` или null. Предикатът има сигнатура `function ($value, $key, iterable $iterable): bool`.
+Връща ключа на първия елемент на итератора. Ако е зададен `$predicate`, връща ключа на първия елемент, който отговаря на даденото условие. Функцията `$predicate` има сигнатура `function ($value, $key, iterable $iterable): bool`. Ако не е намерен съответстващ елемент, се извиква функцията `$else` (ако е предоставена) и се връща нейният резултат. Ако не е предоставена `$else`, се връща `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]
+-------------------------------------------------------------------
 
-Итератор, който трансформира стойностите чрез извикване на `$transformer`. Той има сигнатура `function ($value, $key, iterable $iterable): bool`. Запазва оригиналните ключове.
+Създава нов итератор, като прилага функцията `$transformer` към всеки елемент на оригиналния итератор. Функцията `$transformer` има сигнатура `function ($value, $key, iterable $iterable): mixed` и нейната върната стойност се използва като нова стойност на елемента.
 
 ```php
 $iterator = new ArrayIterator([1, 2, 3]);
 $iterator = Iterables::map($iterator, fn($v) => $v * 2);
 // 2, 4, 6
 ```
 
+Методът използва генератор, което означава, че трансформацията се извършва инкрементално по време на итерацията. Това е ефективно по отношение на паметта и позволява работа с много големи колекции. Ако не итерирате през всички елементи на получения итератор, спестявате изчислителни усилия, тъй като не всички елементи на първоначалния итератор се обработват.
+
+
+mapWithKeys(iterable $iterable, callable $transformer): Generator .[method]
+---------------------------------------------------------------------------
+
+Създава нов итератор, като трансформира стойностите и ключовете на оригиналния итератор. Функцията `$transformer` има сигнатура `function ($value, $key, iterable $iterable): ?array{$newKey, $newValue}`. Ако `$transformer` върне `null`, елементът се прескача. За запазените елементи първият елемент от върнатия масив се използва като нов ключ, а вторият елемент - като нова стойност.
+
+```php
+$iterator = new ArrayIterator(['a' => 1, 'b' => 2]);
+$iterator = Iterables::mapWithKeys($iterator, fn($v, $k) => $v > 1 ? [$v * 2, strtoupper($k)] : null);
+// [4 => 'B']
+```
+
+Подобно на `map()`, този метод използва генератор за поетапна обработка и ефективност на паметта. Това позволява работа с големи колекции и спестяване на изчислителни усилия чрез обработване само на част от резултата.
+
+
+memoize(iterable $iterable): IteratorAggregate .[method]
+--------------------------------------------------------
+
+Създава обвивка около итератор, която кешира ключовете и стойностите му по време на итерацията. Това позволява многократно итериране на данните, без да се налага да се обработва отново оригиналният източник на данни.
+
+```php
+$iterator = /* data that cannot be iterated multiple times */
+$memoized = Iterables::memoize($iterator);
+// Now you can iterate $memoized multiple times without data loss
+```
+
+Този метод е полезен в ситуации, в които е необходимо да се итерира многократно един и същ набор от данни, но оригиналният итератор не поддържа многократна итерация или многократната итерация би била скъпа (например четене на данни от база данни или файл).
+
 
 some(iterable $iterable, callable $predicate): bool .[method]
 -------------------------------------------------------------
 
-Проверява дали поне един елемент от итератора преминава тест, реализиран в `$predicate` със сигнатура `function ($value, $key, iterable $iterable): bool`.
+Проверява дали поне един елемент от итератора отговаря на условието, дефинирано в `$predicate`. Функцията `$predicate` има сигнатура `function ($value, $key, iterable $iterable): bool` и трябва да върне `true` за поне един елемент, за да може методът `some()` да върне `true`.
 
 ```php
 $iterator = new ArrayIterator([1, 30, 39, 29, 10, 13]);
 $isEven = fn($value) => $value % 2 === 0;
 $res = Iterables::some($iterator, $isEven); // true
 ```
 
-Вижте [every( |#every()]).
+Този метод е полезен за бърза проверка дали в дадена колекция има поне един елемент, който отговаря на определено условие, например дали колекцията съдържа поне едно четно число.
+
+Вижте [every(). |#every()]
+
+
+toIterator(iterable $iterable): Iterator .[method]
+--------------------------------------------------
+
+Преобразува всеки обект с итерации (масив, Traversable) в итератор. Ако входният обект вече е Iterator, той се връща непроменен.
+
+```php
+$array = [1, 2, 3];
+$iterator = Iterables::toIterator($array);
+// Now you have an Iterator instead of an array
+```
+
+Този метод е полезен, когато трябва да се уверите, че имате Iterator, независимо от типа на входните данни. Това може да бъде полезно при създаване на функции, които работят с различни типове итерационни данни.

utils/bg/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]
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 
 Претърсва низ за всички срещания, съответстващи на регулярен израз, и връща масив, съдържащ намерения израз и всеки подизраз.
 
@@ -550,6 +550,16 @@ Strings::matchAll('žlutý kůň', '~\w+~', captureOffset: true, utf8: true);
 ] */
 ```
 
+Ако `$lazy` е `true`, функцията връща `Generator` вместо масив, което осигурява значителни ползи за производителността при работа с големи низове. Генераторът позволява съвпаденията да се намират постепенно, вместо да се обработва целият низ наведнъж. Това позволява ефективна работа с изключително големи входни текстове. Освен това можете да прекъснете обработката по всяко време, ако откриете желаното съвпадение, което спестява изчислително време.
+
+```php
+$matches = Strings::matchAll($largeText, '~\w+~', lazy: true);
+foreach ($matches as $match) {
+    echo "Found: $match[0]\n";
+    // Processing can be interrupted at any time
+}
+```
+
 
 replace(string $subject, string|array $pattern, string|callable $replacement='', int $limit=-1, bool $captureOffset=false, bool $unmatchedAsNull=false, bool $utf8=false): string .[method]
 -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

utils/cs/@home.texy

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