Java : RoundingMode with Examples

RoundingMode (Java SE 21 & JDK 21) with Examples.
You will find code examples on most RoundingMode methods.

Summary

Specifies a rounding policy for numerical operations capable of discarding precision. Each rounding mode indicates how the least significant returned digit of a rounded result is to be calculated.

Class diagram

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

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

Enum Constants

CEILING

Rounding mode to round towards positive infinity.

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 -> {
    final var ret = decimal.setScale(0, RoundingMode.CEILING);
    System.out.println(decimal + " : " + ret);
});

// Result
// ↓
//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

Rounding mode to round towards zero.

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 -> {
    final var ret = decimal.setScale(0, RoundingMode.DOWN);
    System.out.println(decimal + " : " + ret);
});

// Result
// ↓
//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

Rounding mode to round towards negative infinity.

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 -> {
    final var ret = decimal.setScale(0, RoundingMode.FLOOR);
    System.out.println(decimal + " : " + ret);
});

// Result
// ↓
//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

Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round 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 -> {
    final var ret = decimal.setScale(0, RoundingMode.HALF_DOWN);
    System.out.println(decimal + " : " + ret);
});

// Result
// ↓
//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

Rounding mode to round towards the "nearest neighbor" unless both neighbors are equidistant, in which case, round towards the even neighbor.

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 -> {
    final var ret = decimal.setScale(0, RoundingMode.HALF_EVEN);
    System.out.println(decimal + " : " + ret);
});

// Result
// ↓
//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

Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round 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 -> {
    final var ret = decimal.setScale(0, RoundingMode.HALF_UP);
    System.out.println(decimal + " : " + ret);
});

// Result
// ↓
//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

Rounding mode to assert that the requested operation has an exact result, hence no rounding is necessary.

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 -> {
    try {
        final var ret = decimal.setScale(0, RoundingMode.UNNECESSARY);
        System.out.println(decimal + " : " + ret);
    } catch (ArithmeticException e) {
        System.out.println(decimal + " : ArithmeticException!");
    }
});

// Result
// ↓
//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

Rounding mode to round away from zero.

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 -> {
    final var ret = decimal.setScale(0, RoundingMode.UP);
    System.out.println(decimal + " : " + ret);
});

// Result
// ↓
//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

Methods

static RoundingMode valueOf (int rm)

Returns the RoundingMode object corresponding to a legacy integer rounding mode constant in 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)

Returns the enum constant of this class with the specified name.

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

static RoundingMode[] values ()

Returns an array containing the constants of this enum class, in the order they are declared.

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

// Result
// ↓
//UP
//DOWN
//CEILING
//FLOOR
//HALF_UP
//HALF_DOWN
//HALF_EVEN
//UNNECESSARY

Methods declared in Enum

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

Please see the link below.

Enum with Examples

API Examples
- Number
  - BigDecimal
  - BigInteger
  - Byte
  - Double
  - Float
  - Integer
  - Long
  - Short
- NumberFormat
- Math
- MathContext
- StrictMath

Java : RoundingMode with Examples

Summary

Enum Constants

CEILING

DOWN

FLOOR

HALF_DOWN

HALF_EVEN

HALF_UP

UNNECESSARY

UP

Methods

static RoundingMode valueOf (int rm)

static RoundingMode valueOf (String name)

static RoundingMode[] values ()

Methods declared in Enum

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

Related posts