nette/utils 4.0.10

Author: dg

utils/cs/datetime.texy

@@ -4,6 +4,9 @@ Datum a čas
 .[perex]
 [api:Nette\Utils\DateTime] je třída, která rozšiřuje nativní [php:DateTime] o další funkce.
 
+Oproti svému předchůdci je striktní. Zatímco PHP **tiše akceptuje** nesmyslná data jako `0000-00-00` (převede na `-0001-11-30`) nebo `2024-02-31` (převede na `2024-03-02`), `Nette\Utils\DateTime` v takových případech vyhodí výjimku.
+
+Zároveň **opravuje chování** při přechodu na letní/zimní čas, kdy v nativním PHP může přičtení relativního času (např. `+100 minutes`) "vést k dřívějšímu výslednému času":https://phpfashion.com/cs/100-minut-je-mene-nez-50-paradoxy-php-pri-zmene-casu než přičtení kratšího úseku (např. `+50 minutes`). Nette zajišťuje, že aritmetika funguje intuitivně a `+100 minutes` je vždy více než `+50 minutes`.
 
 Instalace:
 
@@ -46,6 +49,17 @@ DateTime::createFromFormat('d.m.Y', '26.02.1994', 'Europe/London');
 ```
 
 
+static relativeToSeconds(string $str): int .[method]{data-version:4.0.7}
+------------------------------------------------------------------------
+Převede relativní časový údaj na sekundy. Hodí se pro převod časů jako `5 minutes` nebo `2 hours` na číselnou hodnotu.
+
+```php
+DateTime::relativeToSeconds('1 minute'); // 60
+DateTime::relativeToSeconds('10 minutes'); // 600
+DateTime::relativeToSeconds('-1 hour'); // -3600
+```
+
+
 modifyClone(string $modify=''): static .[method]
 ------------------------------------------------
 Vytvoří kopii s upraveným časem.

utils/cs/helpers.texy

@@ -84,3 +84,14 @@ Helpers::getSuggestion($items, 'fo');   // 'foo'
 Helpers::getSuggestion($items, 'barr'); // 'bar'
 Helpers::getSuggestion($items, 'baz');  // 'bar', ne 'baz'
 ```
+
+
+splitClassName(string $name): array .[method]{data-version:4.0.10}
+------------------------------------------------------------------
+
+Rozdělí celý název třídy v PHP na jmenný prostor a zkrácený název třídy. Vrací pole dvou řetězců, kde první prvek je namespace a druhý název třídy.
+
+```php
+Helpers::splitClassName('Nette\Utils\Helpers'); // ['Nette\Utils', 'Helpers']
+Helpers::splitClassName('Foo');                 // ['', 'Foo']
+```

utils/cs/iterables.texy

@@ -140,6 +140,27 @@ $memoized = Iterables::memoize($iterator);
 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).
 
 
+repeatable(callable $factory): IteratorAggregate .[method]{data-version:4.0.10}
+-------------------------------------------------------------------------------
+
+Umožňuje opakovanou iteraci objektů, které to běžně nedovolují, typicky [PHP generátorů |https://www.php.net/manual/en/language.generators.overview.php]. Metoda `repeatable()` tento problém elegantně řeší: místo samotného iterátoru jí předáte funkci, která iterátor vytváří. Tato továrna je pak zavolána automaticky při každém novém průchodu cyklem.
+
+```php
+// Běžný generátor, který nelze projít dvakrát
+$generator = function () {
+	yield 'A';
+	yield 'B';
+};
+
+$iterator = Iterables::repeatable($generator);
+
+foreach ($iterator as $v) echo $v; // Vypíše: AB
+foreach ($iterator as $v) echo $v; // Vypíše: AB (generátor se spustil znovu)
+```
+
+Tato metoda je alternativou k [#memoize()] v situacích, kdy pracujete s **velkým objemem dat**, jelikož `repeatable()` si data neukládá, ale při každém průchodu je generuje znovu.
+
+
 some(iterable $iterable, callable $predicate): bool .[method]
 -------------------------------------------------------------
 

utils/cs/type.texy

@@ -2,8 +2,13 @@ PHP Typ
 *******
 
 .[perex]
-[api:Nette\Utils\Type] je třída pro práci s datovými typy PHP.
+[api:Nette\Utils\Type] reprezentuje datový typ PHP. Slouží k analýze, porovnávání a manipulaci s typy, ať už pocházejí z řetězce nebo z reflexe.
 
+PHP má dnes velmi bohatý typový systém: od skalárních typů (`int`, `string`) přes objekty a rozhraní až po složené typy (union `A|B`, intersection `A&B` nebo disjunktivní normální formy `(A&B)|D`). Navíc existují speciální typy jako `void`, `never`, `mixed` nebo relativní `self` či `static`.
+
+Práce s těmito typy nativně, zejména přes `ReflectionType`, je často zdlouhavá, protože musíte rekurzivně rozlišovat mezi `ReflectionNamedType`, `ReflectionUnionType` a dalšími objekty. Třída `Nette\Utils\Type` toto vše zapouzdřuje a poskytuje **jednotné a srozumitelné API** pro práci s jakýmkoliv typem, který PHP podporuje.
+
+Umožňuje například snadno zjistit, zda jeden typ [akceptuje|#allows] druhý (kompatibilita), [rozšiřovat typy|#with] nebo převádět reflexe na čitelný zápis.
 
 Instalace:
 
@@ -45,6 +50,25 @@ echo $type;      // 'Foo|Bar'
 ```
 
 
+fromValue(mixed $value): Type .[method]{data-version:4.0.10}
+------------------------------------------------------------
+
+Statická metoda, která vytvoří objekt Type podle typu předané hodnoty.
+
+```php
+$type = Type::fromValue('hello'); // 'string'
+$type = Type::fromValue(123);     // 'int'
+$type = Type::fromValue(new stdClass); // 'stdClass'
+```
+
+Pro resources vrací `mixed`, protože PHP typ `resource` nezná. U anonymních tříd vrací nejbližšího předka nebo typ `object`.
+
+```php
+$obj = new class extends Foo { };
+$type = Type::fromValue($obj);    // 'Foo'
+```
+
+
 getNames(): (string|array)[] .[method]
 --------------------------------------
 
@@ -183,8 +207,8 @@ $type->isClassKeyword();   // false
 ```
 
 
-allows(string $type): bool .[method]
-------------------------------------
+allows(string|Type $type): bool .[method]
+-----------------------------------------
 
 Metoda `allows()` ověřuje kompatibilitu typů. Například umožní zjistit, jestli hodnota určitého typu by mohla být předaná jako parametr.
 
@@ -197,3 +221,24 @@ $type->allows('Foo');    // false
 $type = Type::fromString('mixed');
 $type->allows('null');   // true
 ```
+
+
+with(string|Type $type): Type .[method]{data-version:4.0.10}
+------------------------------------------------------------
+
+Vrací objekt Type, který akceptuje jak původní typ, tak i nově přidaný. Vytváří tzv. union type.
+
+Metoda je chytrá a typy zbytečně nezdvojuje. Pokud přidáte typ, který je již obsažen, nebo je nadmnožinou stávajícího typu (např. přidání `mixed` k `string`), vrátí se zjednodušený výsledek.
+
+```php
+$type = Type::fromString('string');
+
+// Rozšíření na nullable string
+echo $type->with('null'); // '?string'
+
+// Vytvoření union typu
+echo $type->with('int');  // 'string|int'
+
+// Přidání typu, který "přebije" vše ostatní
+echo $type->with('mixed'); // 'mixed'
+```

utils/en/datetime.texy

@@ -4,6 +4,9 @@ Date and Time
 .[perex]
 [api:Nette\Utils\DateTime] is a class that extends the native [php:DateTime] with additional useful features.
 
+Compared to the native class, it is strict. While PHP **silently accepts** invalid dates like `0000-00-00` (converts to `-0001-11-30`) or `2024-02-31` (converts to `2024-03-02`), `Nette\Utils\DateTime` throws an exception in such cases.
+
+It also **fixes the behavior** during Daylight Saving Time (DST) transitions, where in native PHP adding a relative time (e.g., `+100 minutes`) can "result in an earlier time":https://phpfashion.com/en/100-minutes-is-less-than-50-php-paradoxes-during-time-changes than adding a shorter period (e.g., `+50 minutes`). Nette ensures that arithmetic works intuitively and `+100 minutes` is always more than `+50 minutes`.
 
 Installation:
 
@@ -46,6 +49,17 @@ DateTime::createFromFormat('d.m.Y', '26.02.1994', 'Europe/London'); // create wi
 ```
 
 
+static relativeToSeconds(string $str): int .[method]{data-version:4.0.7}
+------------------------------------------------------------------------
+Converts a relative time string to seconds. It is useful for converting times like `5 minutes` or `2 hours` to a numeric value.
+
+```php
+DateTime::relativeToSeconds('1 minute'); // 60
+DateTime::relativeToSeconds('10 minutes'); // 600
+DateTime::relativeToSeconds('-1 hour'); // -3600
+```
+
+
 modifyClone(string $modify=''): static .[method]
 ------------------------------------------------
 Creates a copy with a modified time.

utils/en/helpers.texy

@@ -84,3 +84,14 @@ Helpers::getSuggestion($items, 'fo');   // 'foo'
 Helpers::getSuggestion($items, 'barr'); // 'bar'
 Helpers::getSuggestion($items, 'baz');  // 'bar', not 'baz'
 ```
+
+
+splitClassName(string $name): array .[method]{data-version:4.0.10}
+------------------------------------------------------------------
+
+Splits a PHP class name into a namespace and a short class name. Returns an array of two strings where the first is the namespace and the second is the class name.
+
+```php
+Helpers::splitClassName('Nette\Utils\Helpers'); // ['Nette\Utils', 'Helpers']
+Helpers::splitClassName('Foo');                 // ['', 'Foo']
+```

utils/en/iterables.texy

@@ -140,6 +140,27 @@ $memoized = Iterables::memoize($iterator);
 This method is useful in situations where you need to iterate over the same dataset multiple times, but the original iterator doesn't allow repeated iteration, or re-traversing would be costly (e.g., reading data from a database or file).
 
 
+repeatable(callable $factory): IteratorAggregate .[method]{data-version:4.0.10}
+-------------------------------------------------------------------------------
+
+Allows repeated iteration of objects that otherwise do not support it, typically [PHP generators |https://www.php.net/manual/en/language.generators.overview.php]. The `repeatable()` method solves this problem elegantly: instead of passing the iterator itself, you pass a function that creates it. This factory is then called automatically during each iteration loop.
+
+```php
+// A standard generator that cannot be iterated twice
+$generator = function () {
+	yield 'A';
+	yield 'B';
+};
+
+$iterator = Iterables::repeatable($generator);
+
+foreach ($iterator as $v) echo $v; // Prints: AB
+foreach ($iterator as $v) echo $v; // Prints: AB (generator ran again)
+```
+
+This method is an alternative to [#memoize()] in situations where you are working with **large amounts of data**, since `repeatable()` does not cache data, but generates it again during each iteration.
+
+
 some(iterable $iterable, callable $predicate): bool .[method]
 -------------------------------------------------------------
 

utils/en/type.texy

@@ -2,8 +2,13 @@ PHP Type
 ********
 
 .[perex]
-[api:Nette\Utils\Type] is a class for working with PHP data types.
+[api:Nette\Utils\Type] represents a PHP data type. It is used for analyzing, comparing, and manipulating types, whether obtained from a string or reflection.
 
+PHP currently has a very rich type system: from scalar types (`int`, `string`), through objects and interfaces, to complex types (union `A|B`, intersection `A&B`, or disjunctive normal forms `(A&B)|D`). Additionally, there are special types like `void`, `never`, `mixed`, or relative types `self` and `static`.
+
+Working with these types natively, especially via `ReflectionType`, is often cumbersome because you must recursively distinguish between `ReflectionNamedType`, `ReflectionUnionType`, and other objects. The `Nette\Utils\Type` class encapsulates all of this and provides a **unified and intuitive API** for working with any type supported by PHP.
+
+For example, it allows you to easily check if one type [accepts|#allows] another (compatibility), [extend types|#with], or convert reflections into a readable notation.
 
 Installation:
 
@@ -45,6 +50,25 @@ echo $type;      // 'Foo|Bar'
 ```
 
 
+fromValue(mixed $value): Type .[method]{data-version:4.0.10}
+------------------------------------------------------------
+
+Static method that creates a Type object based on the type of the passed value.
+
+```php
+$type = Type::fromValue('hello'); // 'string'
+$type = Type::fromValue(123);     // 'int'
+$type = Type::fromValue(new stdClass); // 'stdClass'
+```
+
+For resources, it returns `mixed`, as PHP does not support the `resource` type. For anonymous classes, it returns the name of the nearest ancestor or `object`.
+
+```php
+$obj = new class extends Foo { };
+$type = Type::fromValue($obj);    // 'Foo'
+```
+
+
 getNames(): (string|array)[] .[method]
 --------------------------------------
 
@@ -183,8 +207,8 @@ $type->isClassKeyword();   // false
 ```
 
 
-allows(string $type): bool .[method]
-------------------------------------
+allows(string|Type $type): bool .[method]
+-----------------------------------------
 
 The `allows()` method checks type compatibility. For example, it can determine if a value of a certain type could be passed as a parameter to a function expecting this type.
 
@@ -197,3 +221,24 @@ $type->allows('Foo');    // false
 $type = Type::fromString('mixed');
 $type->allows('null');   // true
 ```
+
+
+with(string|Type $type): Type .[method]{data-version:4.0.10}
+------------------------------------------------------------
+
+Returns a Type object that accepts both the original type and the one being added. It creates a so-called union type.
+
+The method is clever and does not duplicate types unnecessarily. If you add a type that is already present, or is a superset of the current type (e.g., adding `mixed` to `string`), the result is simplified.
+
+```php
+$type = Type::fromString('string');
+
+// Extending to nullable string
+echo $type->with('null'); // '?string'
+
+// Creating a union type
+echo $type->with('int');  // 'string|int'
+
+// Adding a type that supersedes everything
+echo $type->with('mixed'); // 'mixed'
+```