Latte 関数
*********

.[perex]
テンプレートでは、一般的な PHP 関数に加えて、次の関数も使えます。

.[table-latte-filters]
| `clamp`      | [値を指定した範囲に収める |#clamp()]
| `divisibleBy`| [変数がある数で割り切れるか調べる |#divisibleBy()]
| `even`       | [指定した数が偶数か調べる |#even()]
| `first`      | [配列の最初の要素、または文字列の最初の文字を返す |#first()]
| `group`      | [さまざまな基準でデータをグループ化する |#group()]
| `hasBlock`   | [ブロックの存在を調べる |#hasBlock()]
| `hasTemplate`| [テンプレートの存在を調べる |#hasTemplate()]
| `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): iterable .[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]も参照してください。


hasTemplate(string $name): bool .[method]{data-version:3.0.22}
--------------------------------------------------------------
指定した名前のテンプレートが存在するかどうかを判定します。

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


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|iterable $value, int $start, ?int $length=null, bool $preserveKeys=false): string|array|\Generator .[method]
-------------------------------------------------------------------------------------------------------------------------
配列、文字列、イテレータの一部を取り出します。

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

この関数は、配列に対しては PHP の `array_slice`、文字列に対しては `mb_substr` のように動き、UTF‑8 モードでは `iconv_substr` 関数にフォールバックします。入力が一般的なイテレータの場合は、切り出した要素を yield するジェネレータに変換されます。

`start` が非負なら、配列や文字列の先頭からそのオフセットの位置から始まります。`start` が負なら、末尾からその分だけ手前から始まります。

`length` が指定されていて正なら、最大でその数の要素を含みます。入力が `length` より短ければ、利用できる要素だけが含まれます。`length` が指定されていて負なら、入力の末尾からその数だけ手前で終わります。省略した場合は、`start` から入力の末尾までのすべてが含まれます。

既定では、この関数は整数の配列キーを並べ直してリセットします。この振る舞いは `preserveKeys` を true にすると変えられます。文字列のキーは、このパラメータに関係なく常に保持されます。