Funzioni di Latte
*****************

.[perex]
Oltre alle comuni funzioni di PHP, nei template potete usare anche queste funzioni.

.[table-latte-filters]
| `clamp`      | [limita un valore all'intervallo indicato |#clamp()]
| `divisibleBy`| [verifica se una variabile è divisibile per un numero |#divisibleBy()]
| `even`       | [verifica se il numero indicato è pari |#even()]
| `first`      | [restituisce il primo elemento di un array o il primo carattere di una stringa |#first()]
| `group`      | [raggruppa i dati secondo vari criteri |#group()]
| `hasBlock`   | [rileva l'esistenza di un blocco |#hasBlock()]
| `hasTemplate`| [rileva l'esistenza di un template |#hasTemplate()]
| `last`       | [restituisce l'ultimo elemento di un array o l'ultimo carattere di una stringa |#last()]
| `odd`        | [verifica se il numero indicato è dispari |#odd()]
| `slice`      | [estrae una porzione di un array o di una stringa |#slice()]


Uso
===

Le funzioni si usano allo stesso modo delle comuni funzioni di PHP e possono comparire in tutte le espressioni:

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

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

Le [funzioni personalizzate|custom-functions] si registrano così:

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

Nel template si chiamano poi in questo modo:

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


Funzioni
========


clamp(int|float $value, int|float $min, int|float $max): int|float .[method]
----------------------------------------------------------------------------
Limita un valore all'intervallo indicato, estremi min e max inclusi.

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

Vedi anche il [filtro clamp |filters#clamp].


divisibleBy(int $value, int $by): bool .[method]
------------------------------------------------
Verifica se una variabile è divisibile per un numero.

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


even(int $value): bool .[method]
--------------------------------
Verifica se il numero indicato è pari.

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


first(string|iterable $value): mixed .[method]
----------------------------------------------
Restituisce il primo elemento di un array o il primo carattere di una stringa:

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

Vedi anche [#last()], [filtro first |filters#first].


group(iterable $data, string|int|\Closure $by): iterable .[method]{data-version:3.0.16}
---------------------------------------------------------------------------------------
Questa funzione raggruppa i dati secondo criteri diversi.

In questo esempio le righe della tabella sono raggruppate per la colonna `categoryId`. Il risultato è una struttura iterabile di gruppi, dove la chiave è il valore della colonna `categoryId`. [Leggete la guida dettagliata|cookbook/grouping].

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

Vedi anche il [filtro group |filters#group].


hasBlock(string $name): bool .[method]{data-version:3.0.10}
-----------------------------------------------------------
Verifica se esiste un blocco con il nome indicato:

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

Vedi anche il [controllo dell'esistenza di un blocco |template-inheritance#Verificare l'esistenza di un blocco].


hasTemplate(string $name): bool .[method]{data-version:3.0.22}
--------------------------------------------------------------
Determina se esiste un template con il nome indicato:

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


last(string|array $value): mixed .[method]
------------------------------------------
Restituisce l'ultimo elemento di un array o l'ultimo carattere di una stringa:

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

Vedi anche [#first()], [filtro last |filters#last].


odd(int $value): bool .[method]
-------------------------------
Verifica se il numero indicato è dispari.

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


slice(string|iterable $value, int $start, ?int $length=null, bool $preserveKeys=false): string|array|\Generator .[method]
-------------------------------------------------------------------------------------------------------------------------
Estrae una porzione di un array, di una stringa o di un iteratore.

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

La funzione si comporta come la funzione PHP `array_slice` per gli array o `mb_substr` per le stringhe, con un ripiego sulla funzione `iconv_substr` in modalità UTF‑8. Se l'input è un iteratore generico, viene convertito in un generatore che restituisce gli elementi della porzione.

Se `start` non è negativo, la sequenza inizierà a quella distanza dall'inizio dell'array o della stringa. Se `start` è negativo, la sequenza inizierà a quella distanza dalla fine.

Se `length` è indicato ed è positivo, la sequenza avrà al massimo quel numero di elementi. Se l'input è più corto di `length`, saranno presenti solo gli elementi disponibili. Se `length` è indicato ed è negativo, la sequenza si fermerà a quel numero di elementi dalla fine dell'input. Se viene omesso, la sequenza conterrà tutto da `start` fino alla fine dell'input.

Per impostazione predefinita la funzione riordina e azzera le chiavi intere dell'array. Questo comportamento si può cambiare impostando `preserveKeys` a true. Le chiavi stringa vengono sempre conservate, indipendentemente da questo parametro.