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#Checking block existence]。


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` として機能し、UTF‑8 モードでは `iconv_substr` 関数へのフォールバックがあります。

`start` が正の場合、シーケンスは配列/文字列の先頭からこの数だけオフセットされて開始します。負の場合、シーケンスは末尾からそれだけオフセットされて開始します。

`length` パラメータが指定され、正の場合、シーケンスにはその数の要素が含まれます。この関数に負の `length` パラメータが渡された場合、シーケンスには元の配列のすべての要素が含まれ、`start` 位置から開始し、配列の末尾から `length` 要素少ない位置で終了します。このパラメータを指定しない場合、シーケンスには元の配列のすべての要素が含まれ、`start` 位置から開始します。

デフォルトでは、この関数は順序を変更し、配列の整数キーをリセットします。この動作は、`preserveKeys` を `true` に設定することで変更できます。文字列キーは、このパラメータに関係なく常に保持されます。