Функции Latte
*************

.[perex]
В шаблонах, помимо обычных PHP-функций, мы можем использовать и эти дополнительные функции.

.[table-latte-filters]
| `clamp`      | [ограничивает значение заданным диапазоном |#clamp]
| `divisibleBy`| [проверяет, делится ли переменная на число |#divisibleBy]
| `even`       | [проверяет, является ли данное число четным |#even]
| `first`      | [возвращает первый элемент массива или символ строки |#first]
| `group`      | [группирует данные по различным критериям |#group]
| `hasBlock`   | [проверяет существование блока |#hasBlock]
| `last`       | [возвращает последний элемент массива или символ строки |#last]
| `odd`        | [проверяет, является ли данное число нечетным |#odd]
| `slice`      | [извлекает часть массива или строки |#slice]


Использование
=============

Функции используются так же, как обычные PHP-функции, и их можно использовать во всех выражениях:

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

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

[Пользовательские функции |custom-functions] можно зарегистрировать следующим образом:

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

В шаблоне она вызывается так:

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


Функции
=======


clamp(int|float $value, int|float $min, int|float $max): int|float .[method]
----------------------------------------------------------------------------
Ограничивает значение заданным включительным диапазоном min и max.

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

См. также [фильтр clamp |filters#clamp].


divisibleBy(int $value, int $by): bool .[method]
------------------------------------------------
Проверяет, делится ли переменная на число.

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


even(int $value): bool .[method]
--------------------------------
Проверяет, является ли данное число четным.

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


first(string|iterable $value): mixed .[method]
----------------------------------------------
Возвращает первый элемент массива или символ строки:

```latte
{=first([1, 2, 3, 4])}    {* выводит 1 *}
{=first('abcd')}          {* выводит 'a' *}
```

См. также [#last], [фильтр first |filters#first].


group(iterable $data, string|int|\Closure $by): array .[method]{data-version:3.0.16}
------------------------------------------------------------------------------------
Функция группирует данные по различным критериям.

В этом примере строки в таблице группируются по столбцу `categoryId`. Выводом является массив массивов, где ключом является значение в столбце `categoryId`. [Прочитайте подробное руководство |cookbook/grouping].

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

См. также фильтр [group |filters#group].


hasBlock(string $name): bool .[method]{data-version:3.0.10}
-----------------------------------------------------------
Проверяет, существует ли блок с указанным именем:

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

См. также [проверка существования блоков |template-inheritance#Проверка существования блоков].


last(string|array $value): mixed .[method]
------------------------------------------
Возвращает последний элемент массива или символ строки:

```latte
{=last([1, 2, 3, 4])}    {* выводит 4 *}
{=last('abcd')}          {* выводит 'd' *}
```

См. также [#first], [фильтр last |filters#last].


odd(int $value): bool .[method]
-------------------------------
Проверяет, является ли данное число нечетным.

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


slice(string|array $value, int $start, ?int $length=null, bool $preserveKeys=false): string|array .[method]
-----------------------------------------------------------------------------------------------------------
Извлекает часть массива или строки.

```latte
{=slice('hello', 1, 2)}           {* выводит 'el' *}
{=slice(['a', 'b', 'c'], 1, 2)}   {* выводит ['b', 'c'] *}
```

Функция работает как функция PHP `array_slice` для массивов или `mb_substr` для строк с резервным вариантом на функцию `iconv_substr` в режиме UTF‑8.

Если start положительный, последовательность начнется со смещением на это количество от начала массива/строки. Если отрицательный, последовательность начнется со смещением на столько от конца.

Если указан параметр length и он положительный, последовательность будет содержать столько элементов. Если в эту функцию передан отрицательный параметр length, последовательность будет содержать все элементы исходного массива, начиная с позиции start и заканчивая на позиции, меньшей на length элементов от конца массива. Если этот параметр не указан, последовательность будет содержать все элементы исходного массива, начиная с позиции start.

По умолчанию функция изменяет порядок и сбрасывает целочисленные ключи массива. Это поведение можно изменить, установив preserveKeys в true. Строковые ключи всегда сохраняются, независимо от этого параметра.