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

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * RoundingMode::HalfAwayFromZero を使用した数値の丸め処理のデモンストレーション。
7 *
8 * この関数は NumberFormatter を利用し、HalfAwayFromZero (0.5 をゼロから遠い方向に丸める)
9 * モードで数値をフォーマットする例を示します。
10 * 対象読者はシステムエンジニアを目指す初心者です。
11 */
12function demonstrateHalfAwayFromZeroRounding(): void
13{
14    echo "--- RoundingMode::HalfAwayFromZero のデモンストレーション ---\n";
15
16    // NumberFormatter オブジェクトを作成します。
17    // 'en_US' ロケールを使用し、DECIMAL (十進数) フォーマットを指定します。
18    $formatter = new NumberFormatter('en_US', NumberFormatter::DECIMAL);
19
20    // NumberFormatter に丸めモードを設定します。
21    // RoundingMode::HalfAwayFromZero は、小数点以下がちょうど0.5の場合に、
22    // ゼロから遠い方向に丸めることを意味します。
23    // 例えば、2.5 は 3 に、-2.5 は -3 に丸められます。
24    $formatter->setAttribute(NumberFormatter::ROUNDING_MODE, RoundingMode::HalfAwayFromZero);
25
26    // フォーマットする小数点以下の桁数を0に設定し、結果を整数に丸めます。
27    $formatter->setAttribute(NumberFormatter::MAX_FRACTION_DIGITS, 0);
28
29    echo "\n丸めモード: RoundingMode::HalfAwayFromZero\n";
30    echo "  (特徴: 0.5はゼロから遠い方向へ丸める)\n\n";
31
32    $numbers = [
33        2.5,   // 結果: 3 (ゼロから遠い方向)
34        2.4,   // 結果: 2
35        2.6,   // 結果: 3
36        -2.5,  // 結果: -3 (ゼロから遠い方向)
37        -2.4,  // 結果: -2
38        -2.6,  // 結果: -3
39        0.5,   // 結果: 1
40        -0.5,  // 結果: -1
41        100.0, // 結果: 100
42    ];
43
44    foreach ($numbers as $number) {
45        $formattedNumber = $formatter->format($number);
46        printf("  元の数値: % 6.1f => 丸め後: %s\n", $number, $formattedNumber);
47    }
48
49    echo "\n--- 参考: PHP標準の round() 関数との違い (PHP_ROUND_HALF_UP の場合) ---\n";
50    echo "  round(2.5, 0, PHP_ROUND_HALF_UP): " . round(2.5, 0, PHP_ROUND_HALF_UP) . " (結果: 3)\n";
51    echo "  round(-2.5, 0, PHP_ROUND_HALF_UP): " . round(-2.5, 0, PHP_ROUND_HALF_UP) . " (結果: -2)\n";
52    echo "  ※ RoundingMode::HalfAwayFromZero での -2.5 は -3 となります。\n";
53}
54
55// デモンストレーションを実行します。
56demonstrateHalfAwayFromZeroRounding();

PHPのRoundingMode::HalfAwayFromZeroは、数値を丸める際のルールを定義する定数です。この定数は、PHPの拡張機能であるNumberFormatterなど、数値の書式設定を行う際に使用されます。

この定数が示す丸め方の挙動は、「小数点以下がちょうど0.5の場合に、その数値をゼロから遠い方向に丸める」というものです。例えば、2.5は3に、-2.5は-3に丸められます。これは、正の数では切り上げ、負の数では切り捨てに似た動作になりますが、常にゼロから遠ざかる点が特徴です。引数はなく、この定数自体がRoundingMode型で丸めモードの種類を表します。

サンプルコードでは、NumberFormatterオブジェクトを作成し、setAttribute()メソッドを用いて丸めモードをRoundingMode::HalfAwayFromZeroに設定しています。これにより、指定された数値がこのルールに従って丸められ、整数として出力される例を示しています。

PHP標準のround()関数でPHP_ROUND_HALF_UPを指定した場合、-2.5は-2に丸められますが、RoundingMode::HalfAwayFromZeroでは-3となる点が大きな違いです。この定数を利用することで、国際的な書式設定ルールに則り、より意図に沿った丸め処理を実現できます。

Copy
1<?php
2
3// PHP 8.1以降で利用可能な RoundingMode enum をインポートします。
4// RoundingMode::HalfAwayFromZero は、ちょうど中間の値（例: X.5）を0から遠い方に丸めるモードを定義します。
5// 例えば、2.5は3に丸められ、-2.5は-3に丸められます。
6// リファレンス情報に `RoundingMode::HalfAwayFromZero` が指定されているため、PHP 8.1以降を想定しています。
7use RoundingMode;
8
9/**
10 * 数値を指定された丸めモードで丸め、その後指定された桁数でゼロ埋めして文字列としてフォーマットします。
11 *
12 * この関数は、数値の丸めとゼロ埋めを組み合わせて、固定長の文字列を生成する例です。
13 * 特に、データベースのIDや表示用のコードなど、特定の桁数で表現したい場合に役立ちます。
14 *
15 * @param float        $number       フォーマットする元の数値。
16 * @param int          $precision    丸める小数点以下の桁数。0を指定すると整数に丸められます。
17 * @param RoundingMode $roundingMode 丸めモード（例: RoundingMode::HalfAwayFromZero）。
18 *                                   PHP 8.1以降で利用可能なenumです。
19 *                                   round()関数はPHP 8.3からenumインスタンスを直接受け入れますが、
20 *                                   PHP 8.1/8.2では `$roundingMode->value` を使用して定数値を渡します。
21 * @param int          $totalDigits  ゼロ埋め後の合計桁数 (整数部のみを対象とします)。
22 *                                   元の数値がこの桁数を超えても、切り捨てられずにそのまま表示されます。
23 * @return string                    丸められ、ゼロ埋めされた文字列。
24 */
25function formatAndZerofillNumber(
26    float $number,
27    int $precision,
28    RoundingMode $roundingMode,
29    int $totalDigits
30): string {
31    // 1. 指定された丸めモードで数値を丸める
32    // ここでは RoundingMode::HalfAwayFromZero が適用されます。
33    // PHP 8.1/8.2 の場合、round() 関数の第3引数は int を期待するため、`->value` を使用します。
34    // PHP 8.3 以降であれば `$roundingMode` を直接渡すことも可能です。
35    $roundedNumber = round($number, $precision, $roundingMode->value);
36
37    // ゼロ埋めは通常、整数部に対して行われるため、丸められた結果の整数部分を取得します。
38    // 例: 25.567 -> round(..., 0) -> 26 -> (int)26
39    // 例: -12.5 -> round(..., 0) -> -13 -> (int)-13
40    $integerPart = (int) $roundedNumber;
41
42    // 2. 丸められた整数部分を指定された桁数でゼロ埋めする
43    // sprintf('%0' . $totalDigits . 'd', $integerPart) は以下の処理を行います:
44    // - '%' : フォーマット指定子の開始
45    // - '0' : 桁数が足りない場合、先頭に0を埋める (ゼロ埋め)
46    // - $totalDigits : 埋める桁数（全体の桁数）
47    // - 'd' : 整数 (decimal) としてフォーマットする
48    $zeroFilledString = sprintf('%0' . $totalDigits . 'd', $integerPart);
49
50    return $zeroFilledString;
51}
52
53// --- サンプル使用例 ---
54
55// システムIDやコード番号のように、常に固定の桁数で表示したい数値があると仮定します。
56
57echo "--- RoundingMode::HalfAwayFromZero とゼロ埋めの組み合わせ ---" . PHP_EOL;
58
59// 例1: ポジティブな浮動小数点数を整数に丸めて5桁でゼロ埋め
60$valueA = 25.567;
61$formattedA = formatAndZerofillNumber($valueA, 0, RoundingMode::HalfAwayFromZero, 5);
62echo "元の数値: {$valueA}, 丸め・ゼロ埋め後 (5桁): {$formattedA}" . PHP_EOL; // 出力例: 00026
63
64// 例2: ネガティブな中間値を整数に丸めて5桁でゼロ埋め
65// -12.5 は RoundingMode::HalfAwayFromZero により -13 に丸められます。
66$valueB = -12.5;
67$formattedB = formatAndZerofillNumber($valueB, 0, RoundingMode::HalfAwayFromZero, 5);
68echo "元の数値: {$valueB}, 丸め・ゼロ埋め後 (5桁): {$formattedB}" . PHP_EOL; // 出力例: -0013
69
70// 例3: 99.9を丸めて4桁でゼロ埋め
71// 99.9 は RoundingMode::HalfAwayFromZero により 100 に丸められます。
72$valueC = 99.9;
73$formattedC = formatAndZerofillNumber($valueC, 0, RoundingMode::HalfAwayFromZero, 4);
74echo "元の数値: {$valueC}, 丸め・ゼロ埋め後 (4桁): {$formattedC}" . PHP_EOL; // 出力例: 0100
75
76// 例4: 桁数がゼロ埋め指定よりも多い場合
77// 123456.78を丸めて整数にすると123457。5桁指定でも切り捨てられず、そのまま表示されます。
78$valueD = 123456.78;
79$formattedD = formatAndZerofillNumber($valueD, 0, RoundingMode::HalfAwayFromZero, 5);
80echo "元の数値: {$valueD}, 丸め・ゼロ埋め後 (5桁): {$formattedD}" . PHP_EOL; // 出力例: 123457
81
82// 例5: 小数点以下も含む丸めと、その後のゼロ埋め (ここでは整数部に適用される)
83// 123.456 を小数点以下1桁に丸めると 123.5 になり、整数部は123。
84// ゼロ埋めは整数部に対して行われるため、結果は "0123" (4桁指定) となります。
85$valueE = 123.456;
86$formattedE = formatAndZerofillNumber($valueE, 1, RoundingMode::HalfAwayFromZero, 4);
87echo "元の数値: {$valueE}, 丸め・ゼロ埋め後 (1桁精度, 4桁): {$formattedE}" . PHP_EOL; // 出力例: 0123 (丸め結果123.5の整数部123をゼロ埋め)
88
89?>

PHP 8.1以降で利用可能なRoundingMode::HalfAwayFromZeroは、数値の丸め方を定義するEnumの一員です。このモードは、小数点以下がちょうど中間（例えば2.5や-2.5）の場合に、0から遠い方の整数に丸める挙動を示します。具体的には、2.5は3に、-2.5は-3に丸められます。

本サンプルコードでは、このHalfAwayFromZeroモードでの数値の丸めと、その後のゼロ埋め処理を組み合わせたformatAndZerofillNumber関数を定義しています。この関数は、データベースのIDや表示用のコードなど、常に特定の桁数で数値を表現したい場合に役立ちます。

formatAndZerofillNumber関数は、フォーマットする元の数値（$number）、小数点以下の丸める桁数（$precision）、丸めモード（$roundingMode）、およびゼロ埋め後の合計桁数（$totalDigits）を引数に受け取ります。関数内部では、round()関数を用いて数値を指定されたモードと精度で丸め、その結果の整数部分をsprintf関数で$totalDigitsで指定された桁数にゼロ埋めし、最終的な文字列として返します。戻り値は、丸めとゼロ埋めが適用された文字列です。なお、round()関数はPHP 8.3以降でRoundingModeインスタンスを直接受け入れますが、PHP 8.1/8.2では$roundingMode->valueを使用する必要があります。