- All Implemented Interfaces:
- Serializable,- Comparable<RoundingMode>,- Constable
More generally, a rounding policy defines a mapping from the
 real numbers to a subset of representable values. In the case of
 BigDecimal, the representable values are a function of the
 precision being used in the
 computation. Assuming the mathematical result is within the
 exponent range of BigDecimal, the mathematical result will
 be exactly representable in the result precision or will fall
 between two adjacent representable values. In the case of falling
 between two representable values, the rounding policy determines
 which of those two bracketing values is the result. For in-range
 real numbers, for a given set of representable values, a rounding
 policy maps a continuous segment of the real number line to a
 single representable value where the real number numerically equal
 to a representable value is mapped to that value.
 
Each rounding mode description includes a table listing how
 different two-digit decimal values would round to a one digit
 decimal value under the rounding mode in question.  The result
 column in the tables could be gotten by creating a
 BigDecimal number with the specified value, forming a
 MathContext object with the proper settings
 (precision set to 1, and the
 roundingMode set to the rounding mode in question), and
 calling round on this number with the
 proper MathContext.  A summary table showing the results
 of these rounding operations for all rounding modes appears below.
| Input Number | Result of rounding input to one digit with the given rounding mode | |||||||
|---|---|---|---|---|---|---|---|---|
| UP | DOWN | CEILING | FLOOR | HALF_UP | HALF_DOWN | HALF_EVEN | UNNECESSARY | |
| 5.5 | 6 | 5 | 6 | 5 | 6 | 5 | 6 | throw ArithmeticException | 
| 2.5 | 3 | 2 | 3 | 2 | 3 | 2 | 2 | throw ArithmeticException | 
| 1.6 | 2 | 1 | 2 | 1 | 2 | 2 | 2 | throw ArithmeticException | 
| 1.1 | 2 | 1 | 2 | 1 | 1 | 1 | 1 | throw ArithmeticException | 
| 1.0 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 
| -1.0 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | 
| -1.1 | -2 | -1 | -1 | -2 | -1 | -1 | -1 | throw ArithmeticException | 
| -1.6 | -2 | -1 | -1 | -2 | -2 | -2 | -2 | throw ArithmeticException | 
| -2.5 | -3 | -2 | -2 | -3 | -3 | -2 | -2 | throw ArithmeticException | 
| -5.5 | -6 | -5 | -5 | -6 | -6 | -5 | -6 | throw ArithmeticException | 
This enum is intended to replace the integer-based
 enumeration of rounding mode constants in BigDecimal
 (BigDecimal.ROUND_UP, BigDecimal.ROUND_DOWN,
 etc. ).
- API Note:
- Five of the rounding modes declared in this class correspond to rounding-direction attributes defined in the IEEE Standard for Floating-Point Arithmetic. Where present, this correspondence will be noted in the documentation of the particular constant.
- See Java Language Specification:
- 
15.4 Floating-point Expressions
- Since:
- 1.5
- See Also:
- 
Nested Class SummaryNested classes/interfaces declared in class java.lang.EnumEnum.EnumDesc<E extends Enum<E>>
- 
Enum Constant SummaryEnum ConstantsEnum ConstantDescriptionRounding mode to round towards positive infinity.Rounding mode to round towards zero.Rounding mode to round towards negative infinity.Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round down.Rounding mode to round towards the "nearest neighbor" unless both neighbors are equidistant, in which case, round towards the even neighbor.Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round up.Rounding mode to assert that the requested operation has an exact result, hence no rounding is necessary.Rounding mode to round away from zero.
- 
Method SummaryModifier and TypeMethodDescriptionstatic RoundingModevalueOf(int rm) Returns theRoundingModeobject corresponding to a legacy integer rounding mode constant inBigDecimal.static RoundingModeReturns the enum constant of this class with the specified name.static RoundingMode[]values()Returns an array containing the constants of this enum class, in the order they are declared.
- 
Enum Constant Details- 
UPRounding mode to round away from zero. Always increments the digit prior to a non-zero discarded fraction. Note that this rounding mode never decreases the magnitude of the calculated value.Example: Rounding mode UP Examples Input Number Input rounded to one digit 
 withUProunding5.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 
- 
DOWNRounding mode to round towards zero. Never increments the digit prior to a discarded fraction (i.e., truncates). Note that this rounding mode never increases the magnitude of the calculated value.- API Note:
- This rounding mode is analogous to the rounding policy used
 for the floatanddoubleoperators remainder and conversion to an integer value (JLS 15.4). This mode corresponds to the IEEE 754 rounding-direction attribute roundTowardZero.Example: Rounding mode DOWN Examples Input Number Input rounded to one digit 
 withDOWNrounding5.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 
 
- 
CEILINGRounding mode to round towards positive infinity. If the result is positive, behaves as forRoundingMode.UP; if negative, behaves as forRoundingMode.DOWN. Note that this rounding mode never decreases the calculated value. This mode corresponds to the IEEE 754 rounding-direction attribute roundTowardPositive.Example: Rounding mode CEILING Examples Input Number Input rounded to one digit 
 withCEILINGrounding5.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 
- 
FLOORRounding mode to round towards negative infinity. If the result is positive, behave as forRoundingMode.DOWN; if negative, behave as forRoundingMode.UP. Note that this rounding mode never increases the calculated value. This mode corresponds to the IEEE 754 rounding-direction attribute roundTowardNegative.Example: Rounding mode FLOOR Examples Input Number Input rounded to one digit 
 withFLOORrounding5.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_UPRounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round up. Behaves as forRoundingMode.UPif the discarded fraction is ≥ 0.5; otherwise, behaves as forRoundingMode.DOWN. Note that this is the rounding mode commonly taught at school. This mode corresponds to the IEEE 754 rounding-direction attribute roundTiesToAway.Example: Rounding mode HALF_UP Examples Input Number Input rounded to one digit 
 withHALF_UProunding5.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 
- 
HALF_DOWNRounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round down. Behaves as forRoundingMode.UPif the discarded fraction is > 0.5; otherwise, behaves as forRoundingMode.DOWN.Example: Rounding mode HALF_DOWN Examples Input Number Input rounded to one digit 
 withHALF_DOWNrounding5.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_EVENRounding mode to round towards the "nearest neighbor" unless both neighbors are equidistant, in which case, round towards the even neighbor. Behaves as forRoundingMode.HALF_UPif the digit to the left of the discarded fraction is odd; behaves as forRoundingMode.HALF_DOWNif it's even.- API Note:
- This
 is the rounding mode that statistically minimizes cumulative
 error when applied repeatedly over a sequence of calculations.
 It is sometimes known as "Banker's rounding," and is
 chiefly used in the USA.  This rounding mode is analogous to
 the rounding policy used for most floatanddoublearithmetic operators in Java (JLS 15.4). This mode corresponds to the IEEE 754 rounding-direction attribute roundTiesToEven.Example: Rounding mode HALF_EVEN Examples Input Number Input rounded to one digit 
 withHALF_EVENrounding5.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 
 
- 
UNNECESSARYRounding mode to assert that the requested operation has an exact result, hence no rounding is necessary. If this rounding mode is specified on an operation that yields an inexact result, anArithmeticExceptionis thrown.Example: Rounding mode UNNECESSARY Examples Input Number Input rounded to one digit 
 withUNNECESSARYrounding5.5 throw ArithmeticException2.5 throw ArithmeticException1.6 throw ArithmeticException1.1 throw ArithmeticException1.0 1 -1.0 -1 -1.1 throw ArithmeticException-1.6 throw ArithmeticException-2.5 throw ArithmeticException-5.5 throw ArithmeticException
 
- 
- 
Method Details- 
valuesReturns an array containing the constants of this enum class, in the order they are declared.- Returns:
- an array containing the constants of this enum class, in the order they are declared
 
- 
valueOfReturns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)- Parameters:
- name- the name of the enum constant to be returned.
- Returns:
- the enum constant with the specified name
- Throws:
- IllegalArgumentException- if this enum class has no constant with the specified name
- NullPointerException- if the argument is null
 
- 
valueOfReturns theRoundingModeobject corresponding to a legacy integer rounding mode constant inBigDecimal.- Parameters:
- rm- legacy integer rounding mode to convert
- Returns:
- RoundingModecorresponding to the given integer.
- Throws:
- IllegalArgumentException- integer is out of range
 
 
-