【PHP8.x】RoundingMode::HalfEven定数の使い方

Copy
1<?php
2
3// PHP 8.1以降で利用可能な RoundingMode enum を使用した数値丸め処理の例です。
4// この関数は、NumberFormatter を使って指定された数値を RoundingMode::HalfEven モードで丸めます。
5function handleNumberRoundingHalfEven(float $number): string
6{
7    // ロケール 'en_US' と数値形式 'decimal' を持つ NumberFormatter を作成します。
8    // これにより、数値を国際的な形式で表示できるようになります。
9    $formatter = new NumberFormatter('en_US', NumberFormatter::DECIMAL);
10
11    // NumberFormatter に丸めモードを設定します。
12    // RoundingMode::HalfEven は「銀行家の丸め」とも呼ばれ、
13    // ちょうど中間点 (.5) の値を最も近い偶数に丸めます。
14    // 例: 2.5 は 2 に、3.5 は 4 に丸められます。
15    $formatter->setAttribute(NumberFormatter::ROUNDING_MODE, RoundingMode::HalfEven->value);
16
17    // 丸め処理の精度（小数点以下の桁数）を0に設定します。
18    // これにより、数値は整数に丸められます。
19    $formatter->setAttribute(NumberFormatter::MAX_FRACTION_DIGITS, 0);
20
21    // 設定された丸めモードと精度で数値をフォーマットし、結果を返します。
22    return $formatter->format($number);
23}
24
25// --- サンプル実行 ---
26// RoundingMode::HalfEven の動作を確認するための入力値と出力例を示します。
27echo "--- RoundingMode::HalfEven の例 (中間点を最も近い偶数に丸める) ---\n";
28echo "Input: 2.5, Rounded: " . handleNumberRoundingHalfEven(2.5) . "\n"; // 最も近い偶数2に丸められます
29echo "Input: 3.5, Rounded: " . handleNumberRoundingHalfEven(3.5) . "\n"; // 最も近い偶数4に丸められます
30echo "Input: 4.5, Rounded: " . handleNumberRoundingHalfEven(4.5) . "\n"; // 最も近い偶数4に丸められます
31echo "Input: 5.5, Rounded: " . handleNumberRoundingHalfEven(5.5) . "\n"; // 最も近い偶数6に丸められます
32echo "Input: 2.1, Rounded: " . handleNumberRoundingHalfEven(2.1) . "\n"; // 通常の丸め (2)
33echo "Input: 2.9, Rounded: " . handleNumberRoundingHalfEven(2.9) . "\n"; // 通常の丸め (3)
34
35// --- 参考: RoundingMode::HalfUp (一般的な四捨五入) との比較 ---
36// HalfUp は中間点 (.5) の値を常に切り上げます。
37echo "\n--- 参考: RoundingMode::HalfUp の例 (一般的な四捨五入) ---\n";
38$formatterHalfUp = new NumberFormatter('en_US', NumberFormatter::DECIMAL);
39$formatterHalfUp->setAttribute(NumberFormatter::ROUNDING_MODE, NumberFormatter::ROUND_HALFUP);
40$formatterHalfUp->setAttribute(NumberFormatter::MAX_FRACTION_DIGITS, 0);
41
42echo "Input: 2.5, Rounded: " . $formatterHalfUp->format(2.5) . "\n"; // 切り上げ (3)
43echo "Input: 3.5, Rounded: " . $formatterHalfUp->format(3.5) . "\n"; // 切り上げ (4)
44echo "Input: 4.5, Rounded: " . $formatterHalfUp->format(4.5) . "\n"; // 切り上げ (5)
45echo "Input: 5.5, Rounded: " . $formatterHalfUp->format(5.5) . "\n"; // 切り上げ (6)
46
47?>

このPHPサンプルコードは、PHP 8.1以降で利用可能なRoundingMode enumのHalfEvenモードを用いた数値の丸め処理を解説しています。特に、国際的な数値フォーマットを提供するNumberFormatterクラスを利用して、指定された数値を特定のルールで丸める方法を示しています。

RoundingMode::HalfEvenは「銀行家の丸め」とも呼ばれ、ちょうど中間点である「.5」の値を、最も近い偶数に丸めるという特徴があります。例えば、2.5は2に丸められ、3.5は4に丸められます。これは、丸め処理による数値の統計的な偏りを減らすために利用されることがあります。

handleNumberRoundingHalfEven関数は、引数として受け取った浮動小数点数（float）を、このHalfEvenモードで整数に丸めて文字列（string）として返します。関数内部では、NumberFormatterのROUNDING_MODE属性にRoundingMode::HalfEvenを設定し、MAX_FRACTION_DIGITSを0に設定することで小数点以下をなくし、整数への丸めを実現しています。

実際の実行例を見ると、2.5が「2」に、3.5が「4」に丸められていることが確認でき、中間点が偶数側に丸められるHalfEvenの挙動が明確に示されています。一般的な四捨五入であるRoundingMode::HalfUpが常に中間点を切り上げる（例えば2.5が3になる）のと比較すると、HalfEvenモードの独特な特性が理解できます。この機能は、会計や統計処理など、厳密な数値丸めが求められる場面で活用されます。

Copy
1<?php
2
3/**
4 * RoundingMode 列挙型は PHP 8.1 で導入されました。
5 * このサンプルコードは PHP 8.1 以降のバージョンで動作します。
6 */
7
8/**
9 * 数値の丸め処理を「ハンドリング」する関数。
10 * `RoundingMode::HalfEven` (最近接偶数への丸め) を使用して数値を丸めます。
11 *
12 * `HalfEven` モードは、数値の小数点以下がちょうど中間値 (例: x.5) の場合に、
13 * 最も近い偶数に丸めるという特徴があります。
14 * 例えば、2.5 は 2 に、3.5 は 4 に丸められます。
15 * これは、統計的な偏りを減らすために金融計算などで用いられることが多い丸め方です。
16 *
17 * @param float $value 丸める数値。
18 * @param int $precision 丸め後の小数点以下の桁数。デフォルトは0 (整数に丸める)。
19 * @return float 丸められた数値。
20 */
21function handleRounding(float $value, int $precision = 0): float
22{
23    // PHP 8.1 以降の `round()` 関数は、第3引数で丸めモードを指定できます。
24    // `RoundingMode::HalfEven` は、PHP 8.1 で導入された列挙型 (enum) の定数です。
25    return round($value, $precision, RoundingMode::HalfEven);
26}
27
28// --- サンプルコードの実行例 ---
29
30echo "--- RoundingMode::HalfEven の動作例 ---" . PHP_EOL;
31
32// 2.5 は最も近い偶数である 2 に丸められる
33$value1 = 2.5;
34$roundedValue1 = handleRounding($value1);
35echo "Input: {$value1}, Rounded (HalfEven): {$roundedValue1}" . PHP_EOL;
36
37// 3.5 は最も近い偶数である 4 に丸められる
38$value2 = 3.5;
39$roundedValue2 = handleRounding($value2);
40echo "Input: {$value2}, Rounded (HalfEven): {$roundedValue2}" . PHP_EOL;
41
42// 通常の四捨五入と同じ動作の場合
43$value3 = 2.1;
44$roundedValue3 = handleRounding($value3);
45echo "Input: {$value3}, Rounded (HalfEven): {$roundedValue3}" . PHP_EOL;
46
47$value4 = 2.9;
48$roundedValue4 = handleRounding($value4);
49echo "Input: {$value4}, Rounded (HalfEven): {$roundedValue4}" . PHP_EOL;
50
51// 小数点以下の桁数を指定した場合の HalfEven 丸め
52$value5 = 123.45; // 0.05 が中間値 (末尾の5)
53$roundedValue5 = handleRounding($value5, 1); // 123.45 -> 123.4 (4は偶数)
54echo "Input: {$value5} (precision 1), Rounded (HalfEven): {$roundedValue5}" . PHP_EOL;
55
56$value6 = 123.55; // 0.05 が中間値 (末尾の5)
57$roundedValue6 = handleRounding($value6, 1); // 123.55 -> 123.6 (6は偶数)
58echo "Input: {$value6} (precision 1), Rounded (HalfEven): {$roundedValue6}" . PHP_EOL;
59
60// 負の数の例
61$value7 = -2.5;
62$roundedValue7 = handleRounding($value7); // -2.5 -> -2 (絶対値2.5は2に丸められ、符号は維持)
63echo "Input: {$value7}, Rounded (HalfEven): {$roundedValue7}" . PHP_EOL;
64
65$value8 = -3.5;
66$roundedValue8 = handleRounding($value8); // -3.5 -> -4 (絶対値3.5は4に丸められ、符号は維持)
67echo "Input: {$value8}, Rounded (HalfEven): {$roundedValue8}" . PHP_EOL;
68
69?>

このサンプルコードは、PHP 8.1以降で導入されたRoundingMode::HalfEvenという定数を用いて、数値を丸める処理を説明しています。RoundingMode::HalfEvenは、数値を最も近い偶数に丸める「最近接偶数への丸め」モードを指定します。このモードは、小数点以下がちょうど中間値（例：x.5）の場合に、最も近い偶数に丸められる特徴があります。例えば、2.5は2に、3.5は4に丸められ、統計的な偏りを減らす目的で金融計算などで使用されることが多いです。

サンプルコード内のhandleRounding関数は、このRoundingMode::HalfEvenを使って数値を丸める処理をハンドリングします。引数$valueには丸める数値を浮動小数点数で、$precisionには丸め後の小数点以下の桁数を整数で指定します（デフォルトは0で整数に丸めます）。この関数は丸められた数値を浮動小数点数で返します。

実行例では、2.5が2に、3.5が4に丸められることや、小数点以下の桁数を指定した際に、123.45が123.4（末尾の4が偶数）に、123.55が123.6（末尾の6が偶数）に丸められる様子を確認できます。負の数についても、-2.5が-2に、-3.5が-4に丸められることが示されており、絶対値に対する偶数丸めが適用され、符号が維持されることがわかります。