nette/utils 4.0.5

Author: dg

utils/cs/@home.texy

@@ -5,6 +5,7 @@ Nástroje
 V balíčku `nette/utils` najdete sadu užitečných tříd pro každodenní použití:
 
 | [Callback] | Nette\Utils\Callback
+| [Bezpečné přetypování |cast] | Nette\Utils\Cast
 | [Datum a čas |datetime] | Nette\Utils\DateTime
 | [Finder] | Nette\Utils\Finder
 | [HTML elementy |html-elements] | Nette\Utils\Html

utils/cs/@left-menu.texy

@@ -1,6 +1,7 @@
 Balíček nette/utils
 *******************
 - [Callbacky |callback]
+- [Bezpečné přetypování |cast]
 - [Datum a čas |datetime]
 - [Finder]
 - [Floats]

utils/cs/cast.texy

@@ -0,0 +1,162 @@
+Bezpečné přetypování
+********************
+
+.[perex]
+[api:Nette\Utils\Cast] je třída poskytující bezpečné a bezztrátové přetypování. Na rozdíl od standardních PHP operátorů přetypování vyhodí TypeError, pokud by konverze vedla ke ztrátě dat. Podporuje typy bool, int, float, string a array.
+
+Instalace:
+
+```shell
+composer require nette/utils
+```
+
+Všechny příklady předpokládají vytvořený alias:
+
+```php
+use Nette\Utils\Cast;
+```
+
+
+Motivace
+========
+
+Běžné přetypování v PHP může být zrádné a vést k neočekávaným výsledkům:
+
+```php
+(int) '123abc' === 123;    // část vstupu byla ignorována
+(int) 123.4 === 123;       // dochází ke ztrátě informace
+(string) 1.0 === '1';      // dochází ke ztrátě informace
+```
+
+Třída `Cast` řeší tyto problémy tím, že poskytuje striktní a bezpečné metody přetypování:
+
+```php
+Cast::toInt('123abc');     // vyhodí TypeError
+Cast::toInt(123.4);        // vyhodí TypeError
+Cast::toString(1.0) === '1.0';
+```
+
+Metody třídy `Cast` zajišťují, že:
+
+- Nedojde ke ztrátě dat nebo přesnosti
+- Neplatné vstupy nejsou tiše převedeny na neočekávané hodnoty
+- Komplexní typy (např. objekty) nejsou implicitně převedeny na jednoduché typy
+
+
+Pravidla přetypování
+====================
+
+Následující tabulka shrnuje, jak funguje konverze různých typů vstupních a výstupních hodnot. Nejsou v ní uvedeny případy, kdy má vstup stejný typ jako výstup, pak k žádné konverzi nedochází.
+
+| Vstupní hodnota | Cílový typ | Komentář |
+|-----------------|------------|----------|
+| int, float      | bool       | `0` / `0.0` -> `false`, jinak `true`
+| string          | bool       | `'1'` -> `true`, `'0'` / `''` -> `false`, jinak TypeError
+| null            | bool       | `false`
+| array / object  | bool       | TypeError: nepřevoditelné
+| bool            | int        | `true` -> `1`, `false` -> `0`
+| float           | int        | převede se, pokud je bez desetinné části, jinak TypeError
+| string          | int        | převede se, pokud obsahuje celé číslo, jinak TypeError
+| null            | int        | `0`
+| array / object  | int        | TypeError: nepřevoditelné
+| bool            | float      | `true` -> `1.0`, `false` -> `0.0`
+| int             | float      | převádí se přímo
+| string          | float      | převede se, pokud představuje číslo, jinak TypeError
+| null            | float      | `0.0`
+| array / object  | float      | TypeError: nepřevoditelné
+| bool            | string     | `true` -> `'1'`, `false` -> `'0'`
+| int             | string     | převádí se na řetězcovou reprezentaci
+| float           | string     | převádí se na řetězec, zachovává desetinnou tečku
+| null            | string     | `'0'`
+| array / object  | string     | TypeError: nepřevoditelné
+| null            | array      | `[]`
+| *cokoliv*       | array      | obalí do jednoprvkového pole
+
+
+Třída `Cast` funguje podobně jako nativní type-juggling v PHP, ale s několika důležitými rozdíly, které ji činí bezpečnější a předvídatelnější alternativou.
+
+Vyžaduje přesný formát řetězců bez dodatečných znaků:
+
+```php
+Cast::toInt('123abc');          // vyhodí TypeError
+Cast::toInt('');                // vyhodí TypeError
+```
+
+Zabraňuje ztrátě informace z čísla:
+
+```php
+Cast::toInt(123.4);             // vyhodí TypeError
+Cast::toInt(PHP_INT_MAX + 1);   // vyhodí TypeError
+```
+
+Neumožňuje přetypování polí ani objektů na skalární typy:
+
+```php
+Cast::toInt([]);                // vyhodí TypeError
+```
+
+Neumožňuje přetypování objektů na pole:
+
+```php
+Cast::toArray($obj) === [$obj]; // obalí objekt do jednoprvkového pole
+```
+
+Nedochází ke zkreslení při přetypování na string:
+
+```php
+Cast::toString(1.0) === '1.0';  // PHP by vrátilo '1'
+Cast::toString(false) === '0';  // PHP by vrátilo ''
+```
+
+
+Metody pro přetypování
+======================
+
+Třída `Cast` poskytuje následující metody pro bezpečné přetypování:
+
+- `toBool(mixed $value): bool`
+- `toInt(mixed $value): int`
+- `toFloat(mixed $value): float`
+- `toString(mixed $value): string`
+- `toArray(mixed $value): array`
+
+Každá z těchto metod má také variantu `...OrNull()`, která vrací null, pokud je vstupní hodnota null. Tedy nedochází k přetypování null:
+
+- `toBoolOrNull(mixed $value): ?bool`
+- `toIntOrNull(mixed $value): ?int`
+- `toFloatOrNull(mixed $value): ?float`
+- `toStringOrNull(mixed $value): ?string`
+- `toArrayOrNull(mixed $value): ?array`
+
+
+Další metody
+============
+
+to(mixed $value, string $type): mixed .[method]
+-----------------------------------------------
+Bezpečně převede hodnotu na zadaný typ. Podporované typy jsou `'bool'`, `'int'`, `'float'`, `'string'` a `'array'`.
+
+```php
+$result = Cast::to($value, 'int');
+```
+
+
+toOrNull(mixed $value, string $type): mixed .[method]
+-----------------------------------------------------
+Bezpečně převede hodnotu na zadaný typ, ale vrací null, pokud je vstupní hodnota null. Podporované typy jsou `'bool'`, `'int'`, `'float'`, `'string'` a `'array'`.
+
+```php
+$result = Cast::toOrNull($value, 'int');
+```
+
+
+falseToNull(mixed $value): mixed .[method]
+------------------------------------------
+Převede `false` na `null`, ostatní hodnoty nemění. Tato metoda je užitečná při práci se staršími PHP funkcemi, které v případě neúspěchu vracejí `false`, a umožňuje elegantně převést staré rozhraní na modernější API používající `null`.
+
+```php
+$row = Cast::falseToNull($pdo->fetch(PDO::FETCH_ASSOC));
+if ($row === null) {
+	echo 'Žádné další řádky';
+}
+```

utils/cs/helpers.texy

@@ -53,13 +53,7 @@ Helpers::compare(10, '<', 20); // true
 
 falseToNull(mixed $value): mixed .[method]
 ------------------------------------------
-
-Převádí `false` na `null`, jiné hodnoty nemění.
-
-```php
-Helpers::falseToNull(false); // null
-Helpers::falseToNull(123);   // 123
-```
+Použijte [Cast::falseToNull()|Cast#falseToNull].
 
 
 getLastError(): string .[method]