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

.[perex]
V šablonách můžeme kromě běžných PHP funkcí používat i tyto další.

.[table-latte-filters]
| `clamp`      | [ohraničí hodnotu do daného rozsahu |#clamp]
| `divisibleBy`| [zkontroluje, zda je proměnná dělitelná číslem |#divisibleBy]
| `even`       | [zkontroluje, zda je dané číslo sudé |#even]
| `first`      | [vrací první prvek pole nebo znak řetězce |#first]
| `group`      | [seskupí data podle různých kritérií |#group]
| `hasBlock`   | [zjistí existenci bloku |#hasBlock]
| `hasTemplate`| [zjistí existenci šablony |#hasTemplate]
| `last`       | [vrací poslední prvek pole nebo znak řetězce |#last]
| `odd`        | [zkontroluje, zda je dané číslo liché |#odd]
| `slice`      | [extrahuje část pole nebo řetězce |#slice]


Použití
=======

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

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

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

[Vlastní funkce|custom-functions] lze registrovat tímto způsobem:

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

V šabloně se potom volá takto:

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


Funkce
======


clamp(int|float $value, int|float $min, int|float $max): int|float .[method]
----------------------------------------------------------------------------
Ohraničí hodnotu do daného inkluzivního rozsahu min a max.

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

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


divisibleBy(int $value, int $by): bool .[method]
------------------------------------------------
Zkontroluje, zda je proměnná dělitelná číslem.

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


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

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


first(string|iterable $value): mixed .[method]
----------------------------------------------
Vrací první prvek pole nebo 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): iterable .[method]{data-version:3.0.16}
---------------------------------------------------------------------------------------
Funkce seskupí data podle různých kritérií.

V tomto příkladu se řádky v tabulce seskupují podle sloupce `categoryId`. Výstupem je iterovatelná struktura skupin, kde klíčem je hodnota ve sloupci `categoryId`. [Přečtěte si podrobný návod|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}
-----------------------------------------------------------
Zjistí, zda blok uvedeného jména existuje:

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

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


hasTemplate(string $name): bool .[method]{data-version:3.0.22}
--------------------------------------------------------------
Zjistí, zda existuje šablona uvedeného jména:

```latte
{if hasTemplate('foo.latte')} ... {/if}
```


last(string|array $value): mixed .[method]
------------------------------------------
Vrací poslední prvek pole nebo 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]
-------------------------------
Zkontroluje, zda je dané číslo liché.

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


slice(string|iterable $value, int $start, ?int $length=null, bool $preserveKeys=false): string|array|\Generator .[method]
-------------------------------------------------------------------------------------------------------------------------
Extrahuje část pole, řetězce nebo iterátoru.

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

Funkce funguje jako PHP funkce `array_slice` pro pole nebo `mb_substr` pro řetězce s fallbackem na funkci `iconv_substr` v režimu UTF‑8. Pokud je vstupem obecný iterátor, je převeden na generátor, který vrací vybrané prvky.

Pokud je start nezáporný, posloupnost začne posunutá o tento počet od začátku pole/řetězce. Pokud je záporný, posloupnost začne posunutá o tolik od konce.

Pokud je zadaný parametr length a je kladný, posloupnost bude obsahovat tolik prvků. Pokud je vstup kratší než length, budou přítomny pouze dostupné prvky. Pokud je do této funkce předán záporný parametr length, posloupnost bude obsahovat všechny prvky původního pole, začínající na pozici start a končící na pozici menší na length prvků od konce pole. Pokud tento parametr nezadáte, posloupnost bude obsahovat všechny prvky původního pole, začínající na pozici start.

Ve výchozím nastavení funkce změní pořadí a resetuje celočíselné klíče pole. Toto chování lze změnit nastavením preserveKeys na true. Řetězcové klíče jsou vždy zachovány, bez ohledu na tento parametr.