【PHP8.4】PHP8.4で様変わりしたround関数のまとめ

[round](https://www.php.net/manual/ja/function.round.php)関数はPHP8.4でだいぶ様変わりしたのですが、日本語版はおろか[英語版](https://www.php.net/manual/en/function.round.php)でもドキュメントがまだ更新されていません。
ということで以下がPHP8.4時点におけるround関数の仕様です。


# シグネチャ

```php
round(int|float $num, int $precision = 0, RoundingMode|int $mode = RoundingMode::HalfAwayFromZero): float
```

まず第三引数`$mode`の型が`int`から`RoundingMode|int`に変わりました。
デフォルト値も[PHP_ROUND_HALF_UP](https://www.php.net/manual/ja/math.constants.php#constant.php-round-half-up)からRoundingMode::HalfAwayFromZeroに変わっています。

もっとも後述しますが、RoundingMode::HalfAwayFromZeroの動作はPHP_ROUND_HALF_UPと同一であり、デフォルトの挙動が変わることはありません。


# RoundingMode

[RoundingMode](https://www.php.net/manual/en/enum.roundingmode.php)のENUMが追加されました。
これは`round()`および類似の関数で使用される、小数点の丸めモードを表す列挙型となります。

元々丸めモードは定数だったのですが、PHP8.4で[丸めモードが8つにまで増えて](https://wiki.php.net/rfc/new_rounding_modes_to_round_function)定数だとたいへんだということで[ENUMが導入されました](https://wiki.php.net/rfc/correctly_name_the_rounding_mode_and_make_it_an_enum)。
命名もわかりやすくなっています。

## RoundingMode::HalfAwayFromZero

四捨五入です。

端数が5だった場合は、0から遠い方に丸められます。
`1.5`は2、`-1.5`は`-2`になります。

これまでのPHP_ROUND_HALF_UPと同一です。


## RoundingMode::HalfTowardsZero

四捨五入です。

端数が5だった場合は、0に近い方に丸められます。
`1.5`は1、`-1.5`は`-1`になります。

これまでのPHP_ROUND_HALF_DOWNと同一です。


## RoundingMode::HalfEven

四捨五入です。

端数が5だった場合は、偶数に丸められます。
`1.5`も`2.5`も2になります。

これまでのPHP_ROUND_HALF_EVENと同一です。

正直存在意義がよくわからない。


## RoundingMode::HalfOdd

四捨五入です。

端数が5だった場合は、奇数に丸められます。
`1.5`は1、`2.5`は3になります。

これまでのPHP_ROUND_HALF_ODDと同一です。

HalfEvenよりも謎の存在。


## RoundingMode::NegativeInfinity

切り捨てです。

`1.5`は1、`-1.5`は`-2`になります。

PHP8.4で追加された丸めモードです。
関数[floor](https://www.php.net/manual/ja/function.floor.php)と同じですが、floorは桁数を指定できないのでroundの完全下位互換になりました。


## RoundingMode::PositiveInfinity

切り上げです。

`1.5`は2、`-1.5`は`-1`になります。

PHP8.4で追加された丸めモードです。
関数[ceil](https://www.php.net/manual/ja/function.ceil.php)と同じですが、ceilは桁数を指定できないのでroundの完全下位互換になりました。


## RoundingMode::TowardsZero

0に近い方に丸めます。

`1.9`は1、`-1.9`は`-1`になります。

PHP8.4で追加された丸めモードです。


## RoundingMode::AwayFromZero

0から遠い方に丸めます。

`1.1`は2、`-1.1`は`-2`になります。

PHP8.4で追加された丸めモードです。


# 使用例

```php
round(1.2345678, 5);                                  // float(1.23457)
round(1.2345678, 5, PHP_ROUND_HALF_UP);               // float(1.23457) 同じ
round(1.2345678, 5, RoundingMode::HalfAwayFromZero);  // float(1.23457) 同じ

round(123456789, -5, RoundingMode::NegativeInfinity); // float(123400000)
```

結果が整数値になった場合でも型はfloatです。
単にPHP_ROUND_HALF_UPをRoundingMode::HalfAwayFromZeroにするだけなので、特に問題なく使えるでしょう。

既存の定数が削除される予定は今のところありません。
ただしPHP8.4で追加された丸めモードには定数がないので、切り捨て切り上げにはRoundingModeをつかう必要があります。
また今後PHP10あたりで削除される可能性もあるので、今のうちに置き換えておくとよいでしょう。


# 感想

何気にいままで桁数指定の切り上げ切り捨てがなかったので、[変な小細工が必要](https://qiita.com/Naoki206/items/6cf4c83a4d7860b28c16)になっていました。
今後はようやく普通に書けるようになりますね。



# おまけ

[round](https://www.php.net/manual/ja/function.round.php)はまだなのに、[bcround](https://www.php.net/manual/ja/function.bcround.php)は何故か既にシグネチャが書き換わっています。
まあそのかわり日本語化が中途半端だったりしますが。

PHPドキュメントの日本語化は、これまで[@mumumu](https://x.com/mumumu)氏が[ほぼ一人で維持していた](https://github.com/php/doc-ja/graphs/contributors)のですが、最近になって[@KentarouTakeda](https://x.com/KentarouTakeda)・[@jdkfx](https://x.com/jdkfx)など[多くの人たちが参加し始めました](https://github.com/php/doc-ja/issues/150)。
みんなもぜひ参加してみてはいかがでしょう。
今なら[created-Makefile-for-php-doc-ja](https://blog.jdkfx.com/created-Makefile-for-php-doc-ja)で[簡単に始められる](https://zenn.dev/fendo181/articles/84074e1ce63306)ようになっていますよ。

まあ私は↓なので何の力にもなれませんけどね。

![01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/26088/873279d9-6913-4160-9e0d-bd49c39e5d8f.png)