Latte funkce
************

.[perex]
V šablonách Latte můžeme kromě běžných PHP funkcí využívat i další speciální funkce, které rozšiřují možnosti při práci s daty a šablonami.

.[table-latte-filters]
| `clamp`      | [omezí hodnotu do zadaného rozsahu |#clamp]
| `divisibleBy`| [ověří dělitelnost čísla |#divisibleBy]
| `even`       | [zkontroluje, zda je číslo sudé |#even]
| `first`      | [získá první prvek pole nebo znak řetězce |#first]
| `group`      | [seskupí data podle zadaných kritérií |#group]
| `hasBlock`   | [ověří existenci bloku |#hasBlock]
| `last`       | [získá poslední prvek pole nebo znak řetězce |#last]
| `odd`        | [zkontroluje, zda je číslo liché |#odd]
| `slice`      | [extrahuje část pole nebo řetězce |#slice]


Použití
=======

Funkce v Latte se používají stejně jako běžné PHP funkce a lze je využít ve všech výrazech:

```latte
<p>{clamp($num, 1, 100)}</p>

{if odd($num)} ... {/if}
```

[Vlastní funkce|extending-latte#funkce] můžete do Latte přidat takto:

```php
$latte = new Latte\Engine;
$latte->addFunction('shortify', fn(string $s, int $len = 10) => mb_substr($s, 0, $len));
```

V šabloně pak tuto funkci můžete volat následovně:

```latte
<p>{shortify($text)}</p>
<p>{shortify($text, 100)}</p>
```


Funkce
======


clamp(int|float $value, int|float $min, int|float $max): int|float .[method]
----------------------------------------------------------------------------
Funkce `clamp` omezí hodnotu do zadaného inkluzivního rozsahu mezi `$min` a `$max`.

```latte
{=clamp($level, 0, 255)}
```

Viz také [filtr clamp|filters#clamp].


divisibleBy(int $value, int $by): bool .[method]
------------------------------------------------
Funkce `divisibleBy` ověří, zda je číslo `$value` dělitelné číslem `$by`.

```latte
{if divisibleBy($num, 5)} ... {/if}
```


even(int $value): bool .[method]
--------------------------------
Funkce `even` zkontroluje, zda je dané číslo sudé.

```latte
{if even($num)} ... {/if}
```


first(string|iterable $value): mixed .[method]
----------------------------------------------
Funkce `first` vrací první prvek pole nebo první znak řetězce:

```latte
{=first([1, 2, 3, 4])}    {* vypíše 1 *}
{=first('abcd')}          {* vypíše 'a' *}
```

Viz také [#last], [filtr first|filters#first].


group(iterable $data, string|int|\Closure $by): array .[method]{data-version:3.0.16}
------------------------------------------------------------------------------------
Funkce `group` seskupí data podle zadaných kritérií.

V tomto příkladu se řádky v tabulce seskupují podle sloupce `categoryId`. Výsledkem je pole polí, kde klíčem je hodnota ve sloupci `categoryId`. [Podrobný návod najdete zde|cookbook/grouping].

```latte
{foreach group($items, categoryId) as $categoryId => $categoryItems}
    <ul>
        {foreach $categoryItems as $item}
            <li>{$item->name}</li>
        {/foreach}
    </ul>
{/foreach}
```

Viz také filtr [group|filters#group].


hasBlock(string $name): bool .[method]{data-version:3.0.10}
-----------------------------------------------------------
Funkce `hasBlock` ověří, zda existuje blok s uvedeným názvem:

```latte
{if hasBlock(header)} ... {/if}
```

Viz také [kontrola existence bloků|template-inheritance#Kontrola existence bloků].


last(string|array $value): mixed .[method]
------------------------------------------
Funkce `last` vrací poslední prvek pole nebo poslední znak řetězce:

```latte
{=last([1, 2, 3, 4])}    {* vypíše 4 *}
{=last('abcd')}          {* vypíše 'd' *}
```

Viz také [#first], [filtr last|filters#last].


odd(int $value): bool .[method]
-------------------------------
Funkce `odd` zkontroluje, zda je dané číslo liché.

```latte
{if odd($num)} ... {/if}
```


slice(string|array $value, int $start, ?int $length=null, bool $preserveKeys=false): string|array .[method]
-----------------------------------------------------------------------------------------------------------
Funkce `slice` extrahuje část pole nebo řetězce.

```latte
{=slice('hello', 1, 2)}           {* vypíše 'el' *}
{=slice(['a', 'b', 'c'], 1, 2)}   {* vypíše ['b', 'c'] *}
```

Tato funkce funguje podobně jako PHP funkce `array_slice` pro pole nebo `mb_substr` pro řetězce (s fallbackem na `iconv_substr` v režimu UTF-8).

- Pokud je `$start` kladný, výsledek začíná od tohoto indexu od začátku pole/řetězce. Pokud je záporný, začíná se od konce.

- Pokud je `$length` kladný, výsledek bude obsahovat tolik prvků. Pokud je záporný, výsledek bude obsahovat všechny prvky kromě posledních `$length` prvků. Pokud není zadán, výsledek bude obsahovat všechny prvky od `$start` do konce.

- Parametr `$preserveKeys` určuje, zda zachovat původní klíče pole. Ve výchozím nastavení (false) jsou číselné klíče resetovány. Řetězcové klíče jsou vždy zachovány bez ohledu na toto nastavení.