The Rounding class provides a type safe enumeration of strategies for handling loss of numeric resolution when rounding. Rounding is typically resolved when quantization constraints are applied to a computed result in order to satisfy the requirements of the type to which the result is to be assigned.
Rounding is an abstract class for all rounding strategies. The primary method of this class is {@link #round(BigDecimal) round}. This method will round a BigDecimal value to the appropriate integer and return a BigInteger object.
{@link BigDecimal} objects are rounded by calling the{@link BigDecimal#setScale(int)} method with the appropriaterounding mode. Several static methods are provided in this class to support this functionality for each of the supported rounding modes. In addition, several static singleton rounding strategies are provided by this class to implement one of the supported routing modes. Each of these rounding strategies are modeled after the rounding strategies provided by {@link BigDecimal}and include:
- up
Rounding 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. This rounding mode is supported by the static {@link #roundUp(BigDecimal) roundUp} method and the Roundingsingletons {@link #GENERAL}, {@link #UNKNOWN} and {@link #UP}. - down
Rounding 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. This rounding mode is supported by the static {@link #roundDown(BigDecimal) roundDown} method and the Roundingsingleton {@link #DOWN}. - floor
Rounding mode to round towards negative infinity. If decimal is positive, behave as round down; if decimal is negative, behave as round up. This rounding mode is supported by the static {@link #roundFloor(BigDecimal) roundFloor} method and the Roundingsingleton {@link #FLOOR}. - ceiling
Rounding mode to round towards positive infinity. If decimal is positive, behave as round up; if decimal is negative, behave as round down. This rounding mode is supported by the static {@link #roundCeiling(BigDecimal) roundCeiling} method and the Roundingsingleton {@link #CEILING}. - half up
Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round up. Behaves as for round up if the discarded fraction is >= .5; otherwise, behaves as for round down. Note that this is the rounding mode that most of us were taught in grade school. Rounding mode to round towards zero. This rounding mode is supported by the static {@link #roundHalfUp(BigDecimal) roundHalfUp} method and the Roundingsingleton {@link #HALF_UP}. - half down
Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round down. Behaves as for round up if the discarded fraction is > .5; otherwise, behaves as for ROUND_DOWN. This rounding mode is supported by the static {@link #roundHalfDown(BigDecimal) roundHalfDown} method and the Roundingsingleton {@link #HALF_DOWN}. - half even
Rounding mode to round towards the "nearest neighbor" unless both neighbors are equidistant, in which case, round towards the even neighbor. Behaves as for round half up if the digit to the left of the discarded fraction is odd; behaves as for round half down if it's even. Note that this is the rounding mode that minimizes cumulative error when applied repeatedly over a sequence of calculations. This rounding mode is supported by the static {@link #roundHalfEven(BigDecimal) roundHalfEven} method and the Roundingsingletons {@link #HALF_EVEN} and {@link #CONVERGENT}. - half floor
Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round "ceiling". Behaves as round half down if the decimal is positive and as round half up if the decimal is negative. Note that there is no half floor rounding mode supported for BigDecimal values. This rounding mode is supported by the static {@link #roundHalfFloor(BigDecimal) roundHalfFloor} method andthe Rounding singleton {@link #HALF_FLOOR}. - half ceiling
Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round "ceiling". Behaves as round half up if the decimal is positive and as round half down if the decimal is negative. Note that there is no half ceiling rounding mode supported for BigDecimal values. This rounding mode is supported by the static {@link #roundHalfFloor(BigDecimal) roundHalfCeiling} method andthe Rounding singleton {@link #HALF_CEILING}.
A specific strategy may be chosen dynamically by invoking forName() or getName() with one of the above strategy names. Alternatively a strategy may be selected by using one of the static singletons.
The truncate and nearest strategies should be preferred since they correspond to capabilities available on many processors. Other rounding strategies may require costly code on practical hardware.
The active class functionality is provided by the quantize method which is normally invoked from Quantization.quantize.
@author Ed Willink, Contributor: Mike Wirthlin
@version $Id: Rounding.java,v 1.29 2007/12/07 06:30:33 cxh Exp $
@since Ptolemy II 2.1
@Pt.ProposedRating Red (Ed.Willink)
@Pt.AcceptedRating Red