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

Copy
1<?php
2
3// このサンプルコードはPHP 8以降で動作します。
4// RoundingMode はPHP 8で導入された列挙型（enum）です。
5use RoundingMode;
6
7/**
8 * RoundingMode::HalfOdd を使用した数値の丸め処理の例を示します。
9 * HalfOdd モードは、端数がちょうど0.5の場合、最も近い奇数に丸めます。
10 * それ以外の場合は、通常の四捨五入と同様に動作します。
11 *
12 * 例:
13 *   - 1.5 は、最も近い奇数である 1 に丸められます。
14 *   - 2.5 は、最も近い奇数である 3 に丸められます。
15 *   - 3.5 は、最も近い奇数である 3 に丸められます。
16 *   - 4.5 は、最も近い奇数である 5 に丸められます。
17 *
18 * @param float $value 丸める対象の数値。
19 * @param int $precision 小数点以下の桁数 (デフォルトは0)。
20 * @return float 丸められた数値。
21 */
22function demonstrateHalfOddRounding(float $value, int $precision = 0): float
23{
24    // round() 関数の第3引数に RoundingMode::HalfOdd を指定し、
25    // 指定された丸めモードで数値を丸めます。
26    $roundedValue = round($value, $precision, RoundingMode::HalfOdd);
27
28    echo "元の値: {$value}, 精度: {$precision}, 丸めモード: HalfOdd => 結果: {$roundedValue}\n";
29
30    return $roundedValue;
31}
32
33// --- サンプル実行 ---
34echo "--- RoundingMode::HalfOdd の動作例 (小数点以下0桁) ---\n";
35
36// キーワード「halford 2」に関連する2.5の例
37demonstrateHalfOddRounding(2.5); // 2.5 は、最も近い奇数である 3 に丸められます。
38demonstrateHalfOddRounding(1.5); // 1.5 は、最も近い奇数である 1 に丸められます。
39demonstrateHalfOddRounding(3.5); // 3.5 は、最も近い奇数である 3 に丸められます。
40demonstrateHalfOddRounding(4.5); // 4.5 は、最も近い奇数である 5 に丸められます。
41
42// 0.5でない場合の例（通常の四捨五入と同様）
43demonstrateHalfOddRounding(2.2); // 2.2 は 2 に丸められます。
44demonstrateHalfOddRounding(2.8); // 2.8 は 3 に丸められます。
45
46echo "\n--- その他の例 (小数点以下の精度を指定) ---\n";
47// 小数点以下第2位で丸める例 (第3位が0.5の基準)
48demonstrateHalfOddRounding(1.235, 2); // 1.235 (1.23と1.24の中間) は 1.23 に丸められます (23が奇数)。
49demonstrateHalfOddRounding(1.245, 2); // 1.245 (1.24と1.25の中間) は 1.25 に丸められます (24が偶数なので次の奇数へ)。
50demonstrateHalfOddRounding(1.255, 2); // 1.255 (1.25と1.26の中間) は 1.25 に丸められます (25が奇数)。
51
52// 負の数の例
53demonstrateHalfOddRounding(-1.5);    // -1.5 は、最も近い奇数である -1 に丸められます。

このサンプルコードは、PHP 8で導入された数値の丸めモードであるRoundingMode::HalfOddの使い方を示しています。RoundingMode::HalfOddは、PHPの標準関数であるround()の第3引数に指定することで、数値を特定のルールに基づいて丸める際に利用します。

この丸めモードの主な特徴は、丸め対象の数値の端数がちょうど0.5である場合に、最も近い「奇数」へと丸める点です。例えば、1.5は最も近い奇数である1に、2.5は3に丸められます。これは、通常の四捨五入では2.5が3に丸められるのに対し、1.5も2に丸められる（偶数丸めや従来の四捨五入）場合があるのとは異なる挙動です。端数が0.5ではない場合は、一般的な四捨五入と同じように動作します。

サンプルコードのdemonstrateHalfOddRounding関数は、丸める対象の数値（$value）と小数点以下の桁数（$precision）を受け取り、round()関数にRoundingMode::HalfOddを指定して丸め処理を実行します。round()関数は、元の数値を指定された精度と丸めモードで丸め、その結果をfloat型で返します。この関数は、丸められた数値を出力しながら返却します。

実行例では、キーワードの2.5が3に丸められる例をはじめ、1.5が1に、3.5が3に丸められる様子が示されています。また、小数点以下の特定の桁での丸めや負の数の丸めについても例があり、HalfOddモードがどのように機能するかを具体的に理解することができます。

Copy
1<?php
2
3/**
4 * PHPの RoundingMode::HalfOdd 定数を使った数値の丸め処理を示すサンプルコードです。
5 *
6 * HalfOddモードは、小数部がちょうど0.5の場合に、最も近い奇数に丸めます。
7 * それ以外の場合、通常の四捨五入と同じように動作します。
8 */
9function demonstrateHalfOddRounding(): void
10{
11    echo "--- RoundingMode::HalfOdd のデモンストレーション ---\n";
12
13    $numbersToRound = [
14        2.5,  // 2に最も近い奇数 -> 3
15        3.5,  // 4に最も近い奇数 -> 3
16        4.5,  // 4に最も近い奇数 -> 5
17        5.5,  // 6に最も近い奇数 -> 5
18        2.4,  // 通常の四捨五入 -> 2
19        2.6,  // 通常の四捨五入 -> 3
20        -2.5, // -2に最も近い奇数 -> -3
21        -3.5, // -4に最も近い奇数 -> -3
22    ];
23
24    foreach ($numbersToRound as $number) {
25        // round() 関数を使用して数値を丸めます。
26        // 第2引数は小数点以下の桁数 (0で整数に丸める)、第3引数は丸めモードです。
27        $roundedNumber = round($number, 0, RoundingMode::HalfOdd);
28        echo "元の数値: " . sprintf("%6.1f", $number) . " => HalfOddで丸めた結果: " . sprintf("%d", $roundedNumber) . "\n";
29    }
30
31    echo "\n--- RoundingMode::HalfOdd と HalfEven の比較 ---\n";
32    // HalfOddと比較のためにHalfEvenを使用します。
33    // HalfEvenは小数部が0.5の場合、最も近い偶数に丸めます。
34    $compareNumbers = [2.5, 3.5];
35
36    foreach ($compareNumbers as $number) {
37        $halfOddResult = round($number, 0, RoundingMode::HalfOdd);
38        $halfEvenResult = round($number, 0, RoundingMode::HalfEven);
39
40        echo "数値: " . sprintf("%6.1f", $number) . "\n";
41        echo "  - HalfOdd (奇数に丸める):  " . sprintf("%d", $halfOddResult) . "\n";
42        echo "  - HalfEven (偶数に丸める): " . sprintf("%d", $halfEvenResult) . "\n";
43    }
44}
45
46// サンプルコードの実行
47demonstrateHalfOddRounding();
48

PHPのRoundingMode::HalfOdd定数は、数値を整数に丸める際に用いられる、特別なルールを定義するものです。これはround()関数などの丸め処理で指定され、最終的に整数値を返します。この定数自体は引数を持ちません。

HalfOddモードの最大の特徴は、小数部の値がちょうど0.5である場合の挙動です。この場合、丸める対象の数値が正負どちらであっても、最も近い「奇数」に丸められます。例えば、2.5は3に、3.5は3に丸められます。一方、-2.5は-3に、-3.5も-3に丸められます。

小数部が0.5以外の場合は、通常の四捨五入と同じ動作をします。例えば2.4は2に、2.6は3に丸められます。

この挙動は、小数部が0.5の際に最も近い「偶数」に丸めるRoundingMode::HalfEven定数と比較すると理解しやすくなります。HalfOddは特定の統計計算などで、丸めによる数値の偏りを意図的に調整したい場合に利用されることがあります。