round関数はPHP8.4でだいぶ様変わりしたのですが、日本語版はおろか英語版でもドキュメントがまだ更新されていません。
ということで以下がPHP8.4時点におけるround関数の仕様です。
シグネチャ
round(int|float $num, int $precision = 0, RoundingMode|int $mode = RoundingMode::HalfAwayFromZero): float
まず第三引数$modeの型がintからRoundingMode|intに変わりました。
デフォルト値もPHP_ROUND_HALF_UPからRoundingMode::HalfAwayFromZeroに変わっています。
もっとも後述しますが、RoundingMode::HalfAwayFromZeroの動作はPHP_ROUND_HALF_UPと同一であり、デフォルトの挙動が変わることはありません。
RoundingMode
RoundingModeのENUMが追加されました。
これはround()および類似の関数で使用される、小数点の丸めモードを表す列挙型となります。
元々丸めモードは定数だったのですが、PHP8.4で丸めモードが8つにまで増えて定数だとたいへんだということで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と同じですが、floorは桁数を指定できないのでroundの完全下位互換になりました。
RoundingMode::PositiveInfinity
切り上げです。
1.5は2、-1.5は-1になります。
PHP8.4で追加された丸めモードです。
関数ceilと同じですが、ceilは桁数を指定できないのでroundの完全下位互換になりました。
RoundingMode::TowardsZero
0に近い方に丸めます。
1.9は1、-1.9は-1になります。
PHP8.4で追加された丸めモードです。
RoundingMode::AwayFromZero
0から遠い方に丸めます。
1.1は2、-1.1は-2になります。
PHP8.4で追加された丸めモードです。
使用例
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あたりで削除される可能性もあるので、今のうちに置き換えておくとよいでしょう。
感想
何気にいままで桁数指定の切り上げ切り捨てがなかったので、変な小細工が必要になっていました。
今後はようやく普通に書けるようになりますね。
おまけ
roundはまだなのに、bcroundは何故か既にシグネチャが書き換わっています。
まあそのかわり日本語化が中途半端だったりしますが。
PHPドキュメントの日本語化は、これまで@mumumu氏がほぼ一人で維持していたのですが、最近になって@KentarouTakeda・@jdkfxなど多くの人たちが参加し始めました。
みんなもぜひ参加してみてはいかがでしょう。
今ならcreated-Makefile-for-php-doc-jaで簡単に始められるようになっていますよ。
まあ私は↓なので何の力にもなれませんけどね。
