nette/utils 4.0.5

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,135 @@
+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) 0.0 === '0';      // dochází ke ztrátě informace
+(bool) false === '';        // neočekávané, jelikož (bool) true === '1'
+```
+
+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(0.0) === '0.0';
+Cast::toString(false) === '0';
+```
+
+Metody třídy `Cast` zajišťují, že:
+
+1. Nedojde ke ztrátě dat nebo přesnosti
+2. Neplatné vstupy nejsou tiše převedeny na neočekávané hodnoty
+3. Komplexní typy (např. objekty) nejsou implicitně převedeny na jednoduché typy
+
+
+Pravidla přetypování
+====================
+
+Třída `Cast` funguje podobně jako nativní type-juggling v PHP, ale s několika důležitými rozdíly:
+
+- **přísnější kontrola řetězců:** při převodu na čísla, vyžaduje přesný formát bez dodatečných znaků
+- **pole a objekty:** neumožňuje přetypování polí ani objektů na skalární typy
+- **převod objektů na pole:** vrátí pole obsahující objekt
+- **přesnější převod na řetězec:**
+
+```php
+Cast::toString(false) === '0';     // (string) false === ''
+Cast::toString('1.0') === '1.0';      (string) 1.0 === '1'
+```
+
+Tyto rozdíly činí Cast bezpečnější a předvídatelnější alternativou k nativnímu přetypování v PHP, zejména v situacích, kde je kritická integrita dat a typová bezpečnost.
+
+Následující tabulka shrnuje, jak jednotlivé metody přetypovávají různé typy vstupních hodnot:
+
+| Vstupní typ | toBool() | toInt() | toFloat() | toString() | toArray() |
+|-------------|----------|---------|-----------|------------|-----------|
+| bool        | ✓        | ✓       | ✓         | ✓          | ✓         |
+| int         | ✓        | ✓       | ✓         | ✓          | ✓         |
+| float       | ✓        | ✓*      | ✓         | ✓          | ✓         |
+| string      | ✓        | ✓*      | ✓*        | ✓          | ✓         |
+| array       | ✗        | ✗       | ✗         | ✗          | ✓         |
+| object      | ✗        | ✗       | ✗         | ✗          | ✗         |
+| null        | ✓        | ✓       | ✓         | ✓          | ✓         |
+
+✓ - Přetypování je vždy povoleno
+✓* - Přetypování je povoleno pokud nedojde ke ztrátě informace
+✗ - Přetypování není povoleno, vyhodí TypeError
+
+
+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
+============
+
+Třída také poskytuje obecné metody pro přetypování:
+
+
+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]