Latte-Funktionen
****************

.[perex]
Zusätzlich zu den üblichen PHP-Funktionen können Sie in Templates auch die folgenden Funktionen verwenden.

.[table-latte-filters]
| `clamp`      | [begrenzt einen Wert auf den angegebenen Bereich |#clamp()]
| `divisibleBy`| [prüft, ob eine Variable durch eine Zahl teilbar ist |#divisibleBy()]
| `even`       | [prüft, ob die angegebene Zahl gerade ist |#even()]
| `first`      | [gibt das erste Element eines Arrays oder das erste Zeichen eines Strings zurück |#first()]
| `group`      | [gruppiert Daten nach verschiedenen Kriterien |#group()]
| `hasBlock`   | [erkennt die Existenz eines Blocks |#hasBlock()]
| `hasTemplate`| [erkennt die Existenz eines Templates |#hasTemplate()]
| `last`       | [gibt das letzte Element eines Arrays oder das letzte Zeichen eines Strings zurück |#last()]
| `odd`        | [prüft, ob die angegebene Zahl ungerade ist |#odd()]
| `slice`      | [extrahiert einen Ausschnitt aus einem Array oder einem String |#slice()]


Verwendung
==========

Funktionen werden genauso wie übliche PHP-Funktionen verwendet und können in allen Ausdrücken eingesetzt werden:

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

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

[Eigene Funktionen|custom-functions] lassen sich auf diese Weise registrieren:

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

Im Template wird sie dann so aufgerufen:

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


Funktionen
==========


clamp(int|float $value, int|float $min, int|float $max): int|float .[method]
----------------------------------------------------------------------------
Begrenzt einen Wert auf den angegebenen Bereich zwischen min und max, jeweils einschließlich.

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

Siehe auch den [Filter clamp |filters#clamp].


divisibleBy(int $value, int $by): bool .[method]
------------------------------------------------
Prüft, ob eine Variable durch eine Zahl teilbar ist.

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


even(int $value): bool .[method]
--------------------------------
Prüft, ob die angegebene Zahl gerade ist.

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


first(string|iterable $value): mixed .[method]
----------------------------------------------
Gibt das erste Element eines Arrays oder das erste Zeichen eines Strings zurück:

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

Siehe auch [#last()], [Filter first |filters#first].


group(iterable $data, string|int|\Closure $by): iterable .[method]{data-version:3.0.16}
---------------------------------------------------------------------------------------
Diese Funktion gruppiert Daten nach verschiedenen Kriterien.

In diesem Beispiel werden die Zeilen der Tabelle nach der Spalte `categoryId` gruppiert. Die Ausgabe ist eine iterierbare Struktur von Gruppen, wobei der Schlüssel der Wert in der Spalte `categoryId` ist. [Lesen Sie die ausführliche Anleitung|cookbook/grouping].

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

Siehe auch den [Filter group |filters#group].


hasBlock(string $name): bool .[method]{data-version:3.0.10}
-----------------------------------------------------------
Prüft, ob ein Block mit dem angegebenen Namen existiert:

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

Siehe auch [Prüfen der Existenz von Blöcken |template-inheritance#Existenzprüfung von Blöcken].


hasTemplate(string $name): bool .[method]{data-version:3.0.22}
--------------------------------------------------------------
Ermittelt, ob ein Template mit dem angegebenen Namen existiert:

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


last(string|array $value): mixed .[method]
------------------------------------------
Gibt das letzte Element eines Arrays oder das letzte Zeichen eines Strings zurück:

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

Siehe auch [#first()], [Filter last |filters#last].


odd(int $value): bool .[method]
-------------------------------
Prüft, ob die angegebene Zahl ungerade ist.

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


slice(string|iterable $value, int $start, ?int $length=null, bool $preserveKeys=false): string|array|\Generator .[method]
-------------------------------------------------------------------------------------------------------------------------
Extrahiert einen Ausschnitt aus einem Array, einem String oder einem Iterator.

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

Die Funktion arbeitet wie die PHP-Funktion `array_slice` für Arrays bzw. `mb_substr` für Strings, mit einem Fallback auf die Funktion `iconv_substr` im UTF‑8-Modus. Ist die Eingabe ein allgemeiner Iterator, wird sie in einen Generator umgewandelt, der die ausgeschnittenen Elemente liefert.

Ist `start` nicht negativ, beginnt die Sequenz an dieser Position vom Anfang des Arrays bzw. des Strings. Ist `start` negativ, beginnt die Sequenz um so viele Elemente vor dem Ende.

Ist `length` angegeben und positiv, enthält die Sequenz höchstens so viele Elemente. Ist die Eingabe kürzer als `length`, sind nur die verfügbaren Elemente enthalten. Ist `length` angegeben und negativ, endet die Sequenz um so viele Elemente vor dem Ende der Eingabe. Wird es weggelassen, enthält die Sequenz alles von `start` bis zum Ende der Eingabe.

Standardmäßig ordnet die Funktion die ganzzahligen Array-Schlüssel neu und setzt sie zurück. Dieses Verhalten lässt sich durch Setzen von `preserveKeys` auf true ändern. String-Schlüssel bleiben unabhängig von diesem Parameter immer erhalten.