nette/utils 4.0.4

utils/bg/@home.texy

@@ -13,6 +13,7 @@
 | [Nette\Utils\Image |images]
 | [Пагинация |paginator] | Nette\Utils\Paginator
 | [Парсинг и генериране на JSON |json] | Nette\Utils\Json
+| [Iterables |iterables] | Nette\Utils\Iterables
 | [Полета |arrays] | Nette\Utils\Arrays
 | [Низове |strings] | Nette\Utils\Strings
 | [Тип Nette\Utils\Type |type]

utils/bg/@left-menu.texy

@@ -8,6 +8,7 @@
 - [Снимки |images]
 - [Обратни извиквания |callback]
 - [Пагинатор |paginator]
+- [Iterables |iterables]
 - [Поле |arrays]
 - [Случайни низове |random]
 - [Струни |strings]

utils/bg/arrays.texy

@@ -15,7 +15,7 @@ composer require nette/utils
 Масиви .[#toc-arrays]
 =====================
 
-[api:Nette\Utils\Arrays] е статичен клас, който съдържа полезни функции за работа с масиви.
+[api:Nette\Utils\Arrays] е статичен клас, който съдържа няколко удобни функции за масиви. Неговият еквивалент за итератори е [Nette\Utils\Iterables |iterables].
 
 Следващите примери предполагат, че псевдонимът вече е създаден:
 
@@ -76,10 +76,10 @@ Arrays::contains(['1', false], 1); // false
 ```
 
 
-every(iterable $array, callable $callback): bool .[method]
-----------------------------------------------------------
+every(array $array, callable $predicate): bool .[method]
+--------------------------------------------------------
 
-Проверява дали всички елементи в масива са преминали теста, реализиран в `$callback` с подпис `function ($value, $key, array $array): bool`.
+Проверява дали всички елементи в масива са преминали теста, реализиран в `$predicate` с подпис `function ($value, $key, array $array): bool`.
 
 ```php
 $array = [1, 30, 39, 29, 10, 13];
@@ -90,16 +90,52 @@ $res = Arrays::every($array, $isBelowThreshold); // true
 Вижте [some( |#some]).
 
 
-first(array $array): mixed .[method]
-------------------------------------
+filter(array $array, callable $predicate): array .[method]{data-version:4.0.4}
+------------------------------------------------------------------------------
+
+Връща нов масив, съдържащ всички двойки ключ-стойност, отговарящи на зададения `$predicate`. Обратното извикване има сигнатурата `function ($value, int|string $key, array $array): bool`.
+
+```php
+Arrays::filter(
+	['a' => 1, 'b' => 2, 'c' => 3],
+	fn($v) => $v < 3,
+);
+// ['a' => 1, 'b' => 2]
+```
+
+
+first(array $array, ?callable $predicate=null, ?callable $else=null): mixed .[method]
+-------------------------------------------------------------------------------------
+
+Връща първия елемент (отговарящ на зададеното предсказание, ако е дадено). Ако няма такъв елемент, връща резултата от извикването на `$else` или null.
+ `$predicate` има сигнатура `function ($value, int|string $key, array $array): bool`.
+
+Той не променя вътрешния указател за разлика от `reset()`. Параметрите `$predicate` и `$else` съществуват от версия 4.0.4.
+
+```php
+Arrays::first([1, 2, 3]);                   // 1
+Arrays::first([1, 2, 3], fn($v) => $v > 2); // 3
+Arrays::first([]);                          // null
+Arrays::first([], else: fn() => false);     // false
+```
 
-Връща първия запис в масива или null, ако масивът е празен. Не променя вътрешния указател, за разлика от `reset()`.
+Вижте [last() |#last()].
+
+
+firstKey(array $array, ?callable $predicate=null): int|string|null .[method]{data-version:4.0.4}
+------------------------------------------------------------------------------------------------
+
+Връща ключа на първия елемент (отговарящ на зададения предикат, ако е зададен) или null, ако няма такъв елемент. `$predicate` има сигнатура `function ($value, int|string $key, array $array): bool`.
 
 ```php
-Arrays::first([1, 2, 3]); // 1
-Масиви::first([]); // null
+Arrays::firstKey([1, 2, 3]);                   // 0
+Arrays::firstKey([1, 2, 3], fn($v) => $v > 2); // 2
+Arrays::firstKey(['a' => 1, 'b' => 2]);        // 'a'
+Arrays::firstKey([]);                          // null
 ```
 
+Вижте [lastKey( |#lastKey()]).
+
 
 flatten(array $array, bool $preserveKeys=false): array .[method]
 ----------------------------------------------------------------
@@ -229,21 +265,43 @@ Arrays::isList(['a' => 1, 'b' => 2]); // false
 ```
 
 
-last(array $array): mixed .[method]
------------------------------------
+last(array $array, ?callable $predicate=null, ?callable $else=null): mixed .[method]
+------------------------------------------------------------------------------------
+
+Връща последния елемент (отговарящ на зададения предикат, ако е зададен). Ако няма такъв елемент, връща резултата от извикването на `$else` или null.
+ `$predicate` има сигнатура `function ($value, int|string $key, array $array): bool`.
+
+Той не променя вътрешния указател за разлика от `end()`. Параметрите `$predicate` и `$else` съществуват от версия 4.0.4.
+
+```php
+Arrays::last([1, 2, 3]);                   // 3
+Arrays::last([1, 2, 3], fn($v) => $v < 3); // 2
+Arrays::last([]);                          // null
+Arrays::last([], else: fn() => false);     // false
+```
+
+Вижте [first( |#first()]).
+
 
-Връща последния запис на масива или null, ако масивът е празен. Не променя вътрешния указател, за разлика от `end()`.
+lastKey(array $array, ?callable $predicate=null): int|string|null .[method]{data-version:4.0.4}
+-----------------------------------------------------------------------------------------------
+
+Връща ключа на последния елемент (отговарящ на зададения предикат, ако е зададен) или null, ако няма такъв елемент. `$predicate` има сигнатура `function ($value, int|string $key, array $array): bool`.
 
 ```php
-Arrays::last([1, 2, 3]); // 3
-Arrays::last([]);        // null
+Arrays::lastKey([1, 2, 3]);                    // 2
+Arrays::lastKey([1, 2, 3], fn($v) => $v < 3);  // 1
+Arrays::lastKey(['a' => 1, 'b' => 2]);         // 'b'
+Arrays::lastKey([]);                           // null
 ```
 
+Вижте [firstKey( |#firstKey()]).
+
 
-map(iterable $array, callable $callback): array .[method]
+map(array $array, callable $transformer): array .[method]
 ---------------------------------------------------------
 
-Извиква `$callback` върху всички елементи на масив и връща масив от върнати стойности. Обратното извикване има сигнатура `function ($value, $key, array $array): bool`.
+Извиква `$transformer` върху всички елементи на масив и връща масив от върнати стойности. Обратното извикване има сигнатура `function ($value, $key, array $array): bool`.
 
 ```php
 $array = ['foo', 'bar', 'baz'];
@@ -325,10 +383,10 @@ $position = Arrays::getKeyOffset($array, 'not-exists'); // vrátí null
 ```
 
 
-some(iterable $array, callable $callback): bool .[method]
----------------------------------------------------------
+some(array $array, callable $predicate): bool .[method]
+-------------------------------------------------------
 
-Проверява се дали поне един елемент от масива е преминал теста, реализиран в `$callback`, с подпис `function ($value, $key, array $array): bool`.
+Проверява се дали поне един елемент от масива е преминал теста, реализиран в `$predicate`, с подпис `function ($value, $key, array $array): bool`.
 
 ```php
 $array = [1, 2, 3, 4];

utils/bg/images.texy

@@ -300,6 +300,11 @@ static isTypeSupported(int $type): bool .[method]
 Определя дали даденият [тип |#Formats] изображение се поддържа.
 
 
+static getSupportedTypes(): array .[method]{data-version:4.0.4}
+---------------------------------------------------------------
+Връща масив от поддържаните типове изображения (константи `ImageType::XXX`).
+
+
 static calculateTextBox(string $text, string $fontFile, float $size, float $angle=0, array $options=[]): array .[method]
 ------------------------------------------------------------------------------------------------------------------------
 Изчислява размерите на правоъгълника, който огражда текст с определен шрифт и размер. Връща асоциативен масив, съдържащ ключовете `left`, `top`, `width`, `height`. Лявото поле може да бъде отрицателно, ако текстът започва с ляв надвес.

utils/bg/iterables.texy

@@ -0,0 +1,119 @@
+Функции на итератора
+********************
+
+.[perex]{data-version:4.0.4}
+[api:Nette\Utils\Iterables] е статичен клас с функции за работа с итератори. Неговият аналог за масиви е [Nette\Utils\Arrays |arrays].
+
+
+Инсталация:
+
+```shell
+composer require nette/utils
+```
+
+Всички примери предполагат създаването на псевдоним:
+
+```php
+use Nette\Utils\Iterables;
+```
+
+
+contains(iterable $iterable, $value): bool .[method]
+----------------------------------------------------
+
+Тества за наличие на стойност в итератора. Използва стриктно сравнение (`===`).
+
+```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]
+-------------------------------------------------------
+
+Тества за наличие на ключ в итератора. Използва стриктно сравнение (`===`).
+
+```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]
+--------------------------------------------------------------
+
+Проверява дали всички елементи на итератора са преминали тест, реализиран в `$predicate` със сигнатура `function ($value, $key, iterable $iterable): bool`.
+
+```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`. Запазва оригиналните ключове.
+
+```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`.
+
+```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
+```
+
+
+firstKey(iterable $iterable, ?callable $predicate=null, ?callable $else=null): mixed .[method]
+----------------------------------------------------------------------------------------------
+
+Връща ключа на първия елемент (отговарящ на предиката, ако е зададен). Ако няма такъв елемент, се връща резултатът от извикването на `$else` или null. Предикатът има сигнатура `function ($value, $key, iterable $iterable): bool`.
+
+```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): array .[method]
+---------------------------------------------------------------
+
+Итератор, който трансформира стойностите чрез извикване на `$transformer`. Той има сигнатура `function ($value, $key, iterable $iterable): bool`. Запазва оригиналните ключове.
+
+```php
+$iterator = new ArrayIterator([1, 2, 3]);
+$iterator = Iterables::map($iterator, fn($v) => $v * 2);
+// 2, 4, 6
+```
+
+
+some(iterable $iterable, callable $predicate): bool .[method]
+-------------------------------------------------------------
+
+Проверява дали поне един елемент от итератора преминава тест, реализиран в `$predicate` със сигнатура `function ($value, $key, iterable $iterable): bool`.
+
+```php
+$iterator = new ArrayIterator([1, 30, 39, 29, 10, 13]);
+$isEven = fn($value) => $value % 2 === 0;
+$res = Iterables::some($iterator, $isEven); // true
+```
+
+Вижте [every( |#every()]).

utils/cs/@home.texy

@@ -8,6 +8,7 @@ V balíčku `nette/utils` najdete sadu užitečných tříd pro každodenní pou
 | [Datum a čas |datetime] | Nette\Utils\DateTime
 | [Finder] | Nette\Utils\Finder
 | [HTML elementy |html-elements] | Nette\Utils\Html
+| [Iterátory |iterables] | Nette\Utils\Iterables
 | [JSON |json] | Nette\Utils\Json
 | [Náhodné řetězce |random] | Nette\Utils\Random
 | [Obrázky |images] | Nette\Utils\Image

utils/cs/@left-menu.texy

@@ -5,6 +5,7 @@ Balíček nette/utils
 - [Finder]
 - [Floats]
 - [HTML elementy |html-elements]
+- [Iterátory |iterables]
 - [JSON]
 - [Náhodné řetězce |random]
 - [Obrázky |images]