Package ptolemy.math

Class Rounding

  • All Implemented Interfaces:
    java.lang.Cloneable
    Direct Known Subclasses:
    Rounding.RoundCeiling, Rounding.RoundDown, Rounding.RoundFloor, Rounding.RoundHalfCeiling, Rounding.RoundHalfDown, Rounding.RoundHalfEven, Rounding.RoundHalfFloor, Rounding.RoundHalfUp, Rounding.RoundUp
    public abstract class Rounding
extends java.lang.Object
implements java.lang.Cloneable
    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 round. This method will round a BigDecimal value to the appropriate integer and return a BigInteger object.

    BigDecimal objects are rounded by calling the BigDecimal.setScale(int) method with the appropriate rounding 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 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 roundUp method and the Rounding singletons GENERAL, UNKNOWN and 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 roundDown method and the Rounding singleton 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 roundFloor method and the Rounding singleton 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 roundCeiling method and the Rounding singleton 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 roundHalfUp method and the Rounding singleton 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 roundHalfDown method and the Rounding singleton 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 roundHalfEven method and the Rounding singletons HALF_EVEN and 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 roundHalfFloor method and the Rounding singleton 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 roundHalfCeiling method and the Rounding singleton 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.

    Since:
    Ptolemy II 2.1
    Version:
    $Id$
    Author:
    Ed Willink, Contributor: Mike Wirthlin
    Pt.AcceptedRating:
    Red
    Pt.ProposedRating:
    Red (Ed.Willink)

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected Rounding​(java.lang.String name)
      Construct a Rounding object with the given String name.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.Object clone()
      Return this, that is, return the reference to this object.
      boolean equals​(java.lang.Object object)
      Determine if the argument represents the same Rounding as this object.
      static Rounding forName​(java.lang.String name)
      Return an instance of this class with the specified name.
      static Rounding getName​(java.lang.String name)
      Return an instance of this class with the specified name, or null if none exists.
      int hashCode()
      Return a hash code value for this object.
      static java.util.Iterator nameIterator()
      Return an iterator for the names of all overflow types.
      abstract java.math.BigInteger round​(java.math.BigDecimal decimal)
      Round the BigDecimal value using the appropriate rounding strategy.
      static java.math.BigDecimal roundCeiling​(java.math.BigDecimal decimal)
      Rounding mode to round towards positive infinity.
      static java.math.BigDecimal roundDown​(java.math.BigDecimal decimal)
      Rounding mode to round towards zero.
      static java.math.BigDecimal roundFloor​(java.math.BigDecimal decimal)
      Rounding mode to round towards negative infinity.
      static java.math.BigDecimal roundHalfCeiling​(java.math.BigDecimal decimal)
      Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round "ceiling".
      static java.math.BigDecimal roundHalfDown​(java.math.BigDecimal decimal)
      Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round down.
      static java.math.BigDecimal roundHalfEven​(java.math.BigDecimal decimal)
      Rounding mode to round towards the "nearest neighbor" unless both neighbors are equidistant, in which case, round towards the even neighbor.
      static java.math.BigDecimal roundHalfFloor​(java.math.BigDecimal decimal)
      Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round "ceiling".
      static java.math.BigDecimal roundHalfUp​(java.math.BigDecimal decimal)
      Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round up.
      static java.math.BigDecimal roundUp​(java.math.BigDecimal decimal)
      Rounding mode to round away from zero.
      java.lang.String toString()
      Return the string representation of this rounding.

      • Methods inherited from class java.lang.Object

        finalize, getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • CEILING

        public static final Rounding.RoundCeiling CEILING
        Singleton implementing ceiling rounding strategy.

      • FLOOR

        public static final Rounding.RoundFloor FLOOR
        Singleton implementing floor rounding strategy.

      • TRUNCATE

        public static final Rounding.RoundFloor TRUNCATE
        Singleton implementing truncate rounding strategy.

      • DOWN

        public static final Rounding.RoundDown DOWN
        Singleton implementing down rounding strategy.

      • UP

        public static final Rounding.RoundUp UP
        Singleton implementing up rounding strategy.

      • HALF_DOWN

        public static final Rounding.RoundHalfDown HALF_DOWN
        Singleton implementing half down rounding strategy.

      • HALF_UP

        public static final Rounding.RoundHalfUp HALF_UP
        Singleton implementing half up rounding strategy.

      • HALF_EVEN

        public static final Rounding.RoundHalfEven HALF_EVEN
        Singleton implementing half even rounding strategy.

      • CONVERGENT

        public static final Rounding.RoundHalfEven CONVERGENT
        Singleton implementing convergent rounding strategy.

      • HALF_CEILING

        public static final Rounding.RoundHalfCeiling HALF_CEILING
        Singleton implementing half ceiling rounding strategy.

      • HALF_FLOOR

        public static final Rounding.RoundHalfFloor HALF_FLOOR
        Singleton implementing half floor rounding strategy.

      • GENERAL

        public static final Rounding GENERAL
        Singleton implementing general rounding strategy.

      • UNKNOWN

        public static final Rounding UNKNOWN
        Singleton implementing unknown rounding strategy.

      • UNNECESSARY

        public static final Rounding UNNECESSARY
        Singleton implementing unnecessary rounding strategy.

    • Constructor Detail

      • Rounding

        protected Rounding​(java.lang.String name)
        Construct a Rounding object with the given String name. This name is used for finding a Rounding object at a later time (@see #forName(String)). This constructor is protected to make a type safe enumeration.
        Parameters:
        name - The String name to give this Rounding strategy.

    • Method Detail

      • clone

        public java.lang.Object clone()
        Return this, that is, return the reference to this object.
        Overrides:
        clone in class java.lang.Object
        Returns:
        This Rounding.

      • equals

        public boolean equals​(java.lang.Object object)
        Determine if the argument represents the same Rounding as this object.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        object - Another object.
        Returns:
        True if the argument represents the same Rounding as this object; false otherwise.

      • forName

        public static Rounding forName​(java.lang.String name)
        Return an instance of this class with the specified name.
        Parameters:
        name - Rounding mode name.
        Returns:
        An instance of Rounding or null if the given name does not match a valid rounding mode.

      • getName

        public static Rounding getName​(java.lang.String name)
                        throws java.lang.IllegalArgumentException
        Return an instance of this class with the specified name, or null if none exists.
        Parameters:
        name - The name of the Rounding strategy to find.
        Returns:
        An instance of Rounding.
        Throws:
        java.lang.IllegalArgumentException - If the string does not match one of the known strategies.

      • hashCode

        public int hashCode()
        Return a hash code value for this object.
        Overrides:
        hashCode in class java.lang.Object

      • nameIterator

        public static java.util.Iterator nameIterator()
        Return an iterator for the names of all overflow types.
        Returns:
        An iterator for the names of all overflow types.

      • round

        public abstract java.math.BigInteger round​(java.math.BigDecimal decimal)
        Round the BigDecimal value using the appropriate rounding strategy. The result is a BigInteger value rounded appropriately. Each class that extends Rounding will provide a mode specific round function.
        Parameters:
        decimal - value to be rounded
        Returns:
        The rounded BigInteger.

      • roundCeiling

        public static java.math.BigDecimal roundCeiling​(java.math.BigDecimal decimal)
        Rounding mode to round towards positive infinity. If decimal is positive, behave as roundUp(java.math.BigDecimal); if decimal is negative, behave as roundDown(java.math.BigDecimal).
        Parameters:
        decimal - The BigDecimal value to round.
        Returns:
        Rounded BigDecimal value
        See Also:
        BigDecimal.ROUND_CEILING

      • roundDown

        public static java.math.BigDecimal roundDown​(java.math.BigDecimal decimal)
        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.
        Parameters:
        decimal - The BigDecimal value to round.
        Returns:
        Rounded BigDecimal value
        See Also:
        BigDecimal.ROUND_DOWN

      • roundFloor

        public static java.math.BigDecimal roundFloor​(java.math.BigDecimal decimal)
        Rounding mode to round towards negative infinity. If decimal is positive, behave as roundDown(java.math.BigDecimal); if decimal is negative, behave as roundUp(java.math.BigDecimal).
        Parameters:
        decimal - The BigDecimal value to round.
        Returns:
        Rounded BigDecimal value
        See Also:
        BigDecimal.ROUND_FLOOR

      • roundHalfCeiling

        public static java.math.BigDecimal roundHalfCeiling​(java.math.BigDecimal decimal)
        Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round "ceiling". Behaves as HALF_ROUND_UP if the decimal is positive and as HALF_ROUND_DOWN if the decimal is negative.

        Note that there is no half ceiling rounding mode supported for BigDecimal values. This method uses a combination of the BigDecimal.ROUND_HALF_UP and BigDecimal.ROUND_HALF_DOWN to perform this new rounding mode.

        Parameters:
        decimal - The BigDecimal value to round.
        Returns:
        Rounded BigDecimal value

      • roundHalfDown

        public static java.math.BigDecimal roundHalfDown​(java.math.BigDecimal decimal)
        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.
        Parameters:
        decimal - The BigDecimal value to round.
        Returns:
        Rounded BigDecimal value
        See Also:
        BigDecimal.ROUND_HALF_UP

      • roundHalfEven

        public static java.math.BigDecimal roundHalfEven​(java.math.BigDecimal decimal)
        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.
        Parameters:
        decimal - The BigDecimal value to round.
        Returns:
        Rounded BigDecimal value
        See Also:
        BigDecimal.ROUND_HALF_EVEN

      • roundHalfFloor

        public static java.math.BigDecimal roundHalfFloor​(java.math.BigDecimal decimal)
        Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round "ceiling". Behaves as HALF_ROUND_DOWN if the decimal is positive and as HALF_ROUND_UP if the decimal is negative.

        Note that there is no half floor rounding mode supported for BigDecimal values. This method uses a combination of the BigDecimal.ROUND_HALF_UP and BigDecimal.ROUND_HALF_DOWN to perform this new rounding mode.

        Parameters:
        decimal - The BigDecimal value to round.
        Returns:
        Rounded BigDecimal value

      • roundHalfUp

        public static java.math.BigDecimal roundHalfUp​(java.math.BigDecimal decimal)
        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.
        Parameters:
        decimal - The BigDecimal value to round.
        Returns:
        Rounded BigDecimal value
        See Also:
        BigDecimal.ROUND_HALF_UP

      • roundUp

        public static java.math.BigDecimal roundUp​(java.math.BigDecimal decimal)
        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.
        Parameters:
        decimal - The BigDecimal value to round.
        Returns:
        Rounded BigDecimal value
        See Also:
        BigDecimal.ROUND_UP

      • toString

        public java.lang.String toString()
        Return the string representation of this rounding.
        Overrides:
        toString in class java.lang.Object
        Returns:
        A String.