Funções Latte
*************

.[perex]
Nos templates, além das funções PHP comuns, podemos usar estas outras funções.

.[table-latte-filters]
| `clamp`      | [limita o valor ao intervalo dado |#clamp]
| `divisibleBy`| [verifica se uma variável é divisível por um número |#divisibleBy]
| `even`       | [verifica se um número dado é par |#even]
| `first`      | [retorna o primeiro elemento de um array ou caractere de uma string |#first]
| `group`      | [agrupa dados por vários critérios |#group]
| `hasBlock`   | [verifica a existência de um bloco |#hasBlock]
| `last`       | [retorna o último elemento de um array ou caractere de uma string |#last]
| `odd`        | [verifica se um número dado é ímpar |#odd]
| `slice`      | [extrai uma parte de um array ou string |#slice]


Uso
===

As funções são usadas da mesma forma que as funções PHP comuns e podem ser usadas em todas as expressões:

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

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

[Funções personalizadas|custom-functions] podem ser registadas desta forma:

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

No template, é chamado assim:

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


Funções
=======


clamp(int|float $value, int|float $min, int|float $max): int|float .[method]
----------------------------------------------------------------------------
Limita o valor ao intervalo inclusivo especificado de min e max.

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

Veja também [o filtro clamp |filters#clamp].


divisibleBy(int $value, int $by): bool .[method]
------------------------------------------------
Verifica se uma variável é divisível por um número.

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


even(int $value): bool .[method]
--------------------------------
Verifica se um número dado é par.

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


first(string|iterable $value): mixed .[method]
----------------------------------------------
Retorna o primeiro elemento de um array ou caractere de uma string:

```latte
{=first([1, 2, 3, 4])}    {* exibe 1 *}
{=first('abcd')}          {* exibe 'a' *}
```

Veja também [#last], [o filtro first |filters#first].


group(iterable $data, string|int|\Closure $by): array .[method]{data-version:3.0.16}
------------------------------------------------------------------------------------
A função agrupa dados por vários critérios.

Neste exemplo, as linhas da tabela são agrupadas pela coluna `categoryId`. A saída é um array de arrays, onde a chave é o valor na coluna `categoryId`. [Leia o tutorial detalhado|cookbook/grouping].

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

Veja também o filtro [group |filters#group].


hasBlock(string $name): bool .[method]{data-version:3.0.10}
-----------------------------------------------------------
Verifica se o bloco com o nome especificado existe:

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

Veja também [verificação da existência de blocos |template-inheritance#Verificando a Existência de Blocos].


last(string|array $value): mixed .[method]
------------------------------------------
Retorna o último elemento de um array ou caractere de uma string:

```latte
{=last([1, 2, 3, 4])}    {* exibe 4 *}
{=last('abcd')}          {* exibe 'd' *}
```

Veja também [#first], [o filtro last |filters#last].


odd(int $value): bool .[method]
-------------------------------
Verifica se um número dado é ímpar.

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


slice(string|array $value, int $start, ?int $length=null, bool $preserveKeys=false): string|array .[method]
-----------------------------------------------------------------------------------------------------------
Extrai uma parte de um array ou string.

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

O filtro funciona como a função PHP `array_slice` para arrays ou `mb_substr` para strings com fallback para a função `iconv_substr` no modo UTF-8.

Se `start` for positivo, a sequência começará deslocada por este número a partir do início do array/string. Se for negativo, a sequência começará deslocada por tanto a partir do fim.

Se o parâmetro `length` for especificado e for positivo, a sequência conterá tantos elementos. Se um parâmetro `length` negativo for passado para esta função, a sequência conterá todos os elementos do array original, começando na posição `start` e terminando na posição `length` elementos antes do fim do array. Se este parâmetro não for especificado, a sequência conterá todos os elementos do array original, começando na posição `start`.

Por padrão, o filtro reordena e redefine as chaves inteiras do array. Este comportamento pode ser alterado definindo `preserveKeys` como `true`. As chaves de string são sempre preservadas, independentemente deste parâmetro.