Java : RoundingMode (丸めモード) - API使用例

RoundingMode (Java SE 21 & JDK 21) の使用例まとめです。
だいたいのメソッドを網羅済みです。
API仕様書のおともにどうぞ。

概要

精度を破棄できる数値演算に「端数処理ポリシー」を指定します。各丸めモードは、丸められた結果の返された最下位の桁の計算方法を指定します。

クラス構成

RoundingMode は、数値の丸め動作をいろいろと定義した列挙型です。
厳密にはちょっと違うかもしれませんが、イメージしやすく言うと、切り上げ・切り捨て・四捨五入などです。

主に BigDecimalクラスの演算で使われます。

final var decimal = new BigDecimal("1.3");
System.out.println(decimal); // 1.3

// 小数部の桁数を 0桁 に丸めます。

// 切り上げ(正の無限大に近づくように丸めます)
final var ret1 = decimal.setScale(0, RoundingMode.CEILING);
System.out.println(ret1); // 2

// 切り捨て(負の無限大に近づくように丸めます)
final var ret2 = decimal.setScale(0, RoundingMode.FLOOR);
System.out.println(ret2); // 1

また、丸めを許容しない厳密な計算をしたい場合、UNNECESSARY が使えます。
丸めが発生する計算をすると、例外を発生させます。

関連記事：小数を誤差なしで計算 (BigDecimal)

列挙型定数

CEILING

正の無限大に近づくように丸めるモードです。

final var decimals = List.of(
        new BigDecimal("5.5"),
        new BigDecimal("2.5"),
        new BigDecimal("1.6"),
        new BigDecimal("1.1"),
        new BigDecimal("1.0"),
        new BigDecimal("-1.0"),
        new BigDecimal("-1.1"),
        new BigDecimal("-1.6"),
        new BigDecimal("-2.5"),
        new BigDecimal("-5.5"));

decimals.forEach(decimal -> {
    // 小数部の桁数を 0桁 に丸めます。
    final var ret = decimal.setScale(0, RoundingMode.CEILING);
    System.out.println(decimal + " : " + ret);
});

// 結果
// ↓
//5.5 : 6
//2.5 : 3
//1.6 : 2
//1.1 : 2
//1.0 : 1
//-1.0 : -1
//-1.1 : -1
//-1.6 : -1
//-2.5 : -2
//-5.5 : -5

DOWN

0に近づくように丸めるモードです。

final var decimals = List.of(
        new BigDecimal("5.5"),
        new BigDecimal("2.5"),
        new BigDecimal("1.6"),
        new BigDecimal("1.1"),
        new BigDecimal("1.0"),
        new BigDecimal("-1.0"),
        new BigDecimal("-1.1"),
        new BigDecimal("-1.6"),
        new BigDecimal("-2.5"),
        new BigDecimal("-5.5"));

decimals.forEach(decimal -> {
    // 小数部の桁数を 0桁 に丸めます。
    final var ret = decimal.setScale(0, RoundingMode.DOWN);
    System.out.println(decimal + " : " + ret);
});

// 結果
// ↓
//5.5 : 5
//2.5 : 2
//1.6 : 1
//1.1 : 1
//1.0 : 1
//-1.0 : -1
//-1.1 : -1
//-1.6 : -1
//-2.5 : -2
//-5.5 : -5

FLOOR

負の無限大に近づくように丸めるモードです。

final var decimals = List.of(
        new BigDecimal("5.5"),
        new BigDecimal("2.5"),
        new BigDecimal("1.6"),
        new BigDecimal("1.1"),
        new BigDecimal("1.0"),
        new BigDecimal("-1.0"),
        new BigDecimal("-1.1"),
        new BigDecimal("-1.6"),
        new BigDecimal("-2.5"),
        new BigDecimal("-5.5"));

decimals.forEach(decimal -> {
    // 小数部の桁数を 0桁 に丸めます。
    final var ret = decimal.setScale(0, RoundingMode.FLOOR);
    System.out.println(decimal + " : " + ret);
});

// 結果
// ↓
//5.5 : 5
//2.5 : 2
//1.6 : 1
//1.1 : 1
//1.0 : 1
//-1.0 : -1
//-1.1 : -2
//-1.6 : -2
//-2.5 : -3
//-5.5 : -6

HALF_DOWN

「もっとも近い数字」に丸める丸めモードです(両隣りの数字が等距離の場合は切り捨てます)。

final var decimals = List.of(
        new BigDecimal("5.5"),
        new BigDecimal("2.5"),
        new BigDecimal("1.6"),
        new BigDecimal("1.1"),
        new BigDecimal("1.0"),
        new BigDecimal("-1.0"),
        new BigDecimal("-1.1"),
        new BigDecimal("-1.6"),
        new BigDecimal("-2.5"),
        new BigDecimal("-5.5"));

decimals.forEach(decimal -> {
    // 小数部の桁数を 0桁 に丸めます。
    final var ret = decimal.setScale(0, RoundingMode.HALF_DOWN);
    System.out.println(decimal + " : " + ret);
});

// 結果
// ↓
//5.5 : 5
//2.5 : 2
//1.6 : 2
//1.1 : 1
//1.0 : 1
//-1.0 : -1
//-1.1 : -1
//-1.6 : -2
//-2.5 : -2
//-5.5 : -5

HALF_EVEN

「もっとも近い数字」に丸める丸めモードです(ただし、両隣りの数字が等距離の場合は偶数側に丸めます)。

final var decimals = List.of(
        new BigDecimal("5.5"),
        new BigDecimal("2.5"),
        new BigDecimal("1.6"),
        new BigDecimal("1.1"),
        new BigDecimal("1.0"),
        new BigDecimal("-1.0"),
        new BigDecimal("-1.1"),
        new BigDecimal("-1.6"),
        new BigDecimal("-2.5"),
        new BigDecimal("-5.5"));

decimals.forEach(decimal -> {
    // 小数部の桁数を 0桁 に丸めます。
    final var ret = decimal.setScale(0, RoundingMode.HALF_EVEN);
    System.out.println(decimal + " : " + ret);
});

// 結果
// ↓
//5.5 : 6
//2.5 : 2
//1.6 : 2
//1.1 : 1
//1.0 : 1
//-1.0 : -1
//-1.1 : -1
//-1.6 : -2
//-2.5 : -2
//-5.5 : -6

HALF_UP

「もっとも近い数字」に丸める丸めモードです(ただし、両隣りの数字が等距離の場合は切り上げます)。

final var decimals = List.of(
        new BigDecimal("5.5"),
        new BigDecimal("2.5"),
        new BigDecimal("1.6"),
        new BigDecimal("1.1"),
        new BigDecimal("1.0"),
        new BigDecimal("-1.0"),
        new BigDecimal("-1.1"),
        new BigDecimal("-1.6"),
        new BigDecimal("-2.5"),
        new BigDecimal("-5.5"));

decimals.forEach(decimal -> {
    // 小数部の桁数を 0桁 に丸めます。
    final var ret = decimal.setScale(0, RoundingMode.HALF_UP);
    System.out.println(decimal + " : " + ret);
});

// 結果
// ↓
//5.5 : 6
//2.5 : 3
//1.6 : 2
//1.1 : 1
//1.0 : 1
//-1.0 : -1
//-1.1 : -1
//-1.6 : -2
//-2.5 : -3
//-5.5 : -6

UNNECESSARY

要求される演算の結果が正確であり、丸めが必要でないことを表す丸めモードです。

final var decimals = List.of(
        new BigDecimal("5.5"),
        new BigDecimal("2.5"),
        new BigDecimal("1.6"),
        new BigDecimal("1.1"),
        new BigDecimal("1.0"),
        new BigDecimal("-1.0"),
        new BigDecimal("-1.1"),
        new BigDecimal("-1.6"),
        new BigDecimal("-2.5"),
        new BigDecimal("-5.5"));

decimals.forEach(decimal -> {
    // 小数部の桁数を 0桁 に丸めます。
    try {
        final var ret = decimal.setScale(0, RoundingMode.UNNECESSARY);
        System.out.println(decimal + " : " + ret);
    } catch (ArithmeticException e) {
        System.out.println(decimal + " : ArithmeticException!");
    }
});

// 結果
// ↓
//5.5 : ArithmeticException!
//2.5 : ArithmeticException!
//1.6 : ArithmeticException!
//1.1 : ArithmeticException!
//1.0 : 1
//-1.0 : -1
//-1.1 : ArithmeticException!
//-1.6 : ArithmeticException!
//-2.5 : ArithmeticException!
//-5.5 : ArithmeticException!

UP

0から離れるように丸めるモードです。

final var decimals = List.of(
        new BigDecimal("5.5"),
        new BigDecimal("2.5"),
        new BigDecimal("1.6"),
        new BigDecimal("1.1"),
        new BigDecimal("1.0"),
        new BigDecimal("-1.0"),
        new BigDecimal("-1.1"),
        new BigDecimal("-1.6"),
        new BigDecimal("-2.5"),
        new BigDecimal("-5.5"));

decimals.forEach(decimal -> {
    // 小数部の桁数を 0桁 に丸めます。
    final var ret = decimal.setScale(0, RoundingMode.UP);
    System.out.println(decimal + " : " + ret);
});

// 結果
// ↓
//5.5 : 6
//2.5 : 3
//1.6 : 2
//1.1 : 2
//1.0 : 1
//-1.0 : -1
//-1.1 : -2
//-1.6 : -2
//-2.5 : -3
//-5.5 : -6

メソッド

static RoundingMode valueOf (int rm)

BigDecimalのレガシー整数丸めモード定数に対応するRoundingModeオブジェクトを返します。

BigDecimalの丸めモード定数は、すべて非推奨となっています。
そのため、基本的に本メソッドを使うことはないと思います。

System.out.println(RoundingMode.valueOf(BigDecimal.ROUND_CEILING)); // CEILING
System.out.println(RoundingMode.valueOf(BigDecimal.ROUND_HALF_DOWN)); // HALF_DOWN

static RoundingMode valueOf (String name)

指定された名前を持つこのクラスのenum定数を返します。

System.out.println(RoundingMode.valueOf("CEILING")); // CEILING
System.out.println(RoundingMode.valueOf("FLOOR")); // FLOOR

static RoundingMode[] values ()

この列挙クラスの定数を含む配列を宣言されている順序で返します。

for (final var value : RoundingMode.values()) {
    System.out.println(value);
}

// 結果
// ↓
//UP
//DOWN
//CEILING
//FLOOR
//HALF_UP
//HALF_DOWN
//HALF_EVEN
//UNNECESSARY

Enumで宣言されたメソッド

clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

「Java API 使用例 : Enum」をご参照ください。

API 使用例