ptolemy.math
Class Rounding

java.lang.Object
  ptolemy.math.Rounding

All Implemented Interfaces:

java.io.Serializable, 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, java.io.Serializable

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: Rounding.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Ed Willink, Contributor: Mike Wirthlin

See Also:

Serialized Form

Accepted Rating:

Red

Proposed Rating:

Red (Ed.Willink)

Nested Class Summary

static class	Rounding.RoundCeiling Rounding class implementing the round ceiling strategy.
static class	Rounding.RoundDown Rounding class implementing the round down strategy.
static class	Rounding.RoundFloor Rounding class implementing the round floor strategy.
static class	Rounding.RoundHalfCeiling Rounding class implementing the round half ceiling strategy.
static class	Rounding.RoundHalfDown Rounding class implementing the round half down strategy.
static class	Rounding.RoundHalfEven Rounding class implementing the round half even strategy.
static class	Rounding.RoundHalfFloor Rounding class implementing the round half floor strategy.
static class	Rounding.RoundHalfUp Rounding class implementing the round half up strategy.
static class	Rounding.RoundUp Rounding class implementing the round up strategy.

Field Summary

private java.lang.String	_name The name of the rounding mode.
private static java.util.Map	_nameToRounding A map from rounding type name to the rounding type for all rounding types.
static Rounding.RoundCeiling	CEILING Singleton implementing ceiling rounding strategy.
static Rounding.RoundHalfEven	CONVERGENT Singleton implementing convergent rounding strategy.
static Rounding.RoundDown	DOWN Singleton implementing down rounding strategy.
static Rounding.RoundFloor	FLOOR Singleton implementing floor rounding strategy.
static Rounding	GENERAL Singleton implementing general rounding strategy.
static Rounding.RoundHalfCeiling	HALF_CEILING Singleton implementing half ceiling rounding strategy.
static Rounding.RoundHalfDown	HALF_DOWN Singleton implementing half down rounding strategy.
static Rounding.RoundHalfEven	HALF_EVEN Singleton implementing half even rounding strategy.
static Rounding.RoundHalfFloor	HALF_FLOOR Singleton implementing half floor rounding strategy.
static Rounding.RoundHalfUp	HALF_UP Singleton implementing half up rounding strategy.
static Rounding.RoundHalfCeiling	NEAREST Singleton implementing nearest rounding strategy.
static Rounding.RoundFloor	TRUNCATE Singleton implementing truncate rounding strategy.
static Rounding	UNKNOWN Singleton implementing unknown rounding strategy.
static Rounding	UNNECESSARY Singleton implementing unnecessary rounding strategy.
static Rounding.RoundUp	UP Singleton implementing up rounding strategy.

Constructor Summary

protected

Rounding(java.lang.String name) Construct a Rounding object with the given String name.

Method Summary

(package private) static void	_addRounding(Rounding type, java.lang.String name)
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.

NEAREST

public static final Rounding.RoundHalfCeiling NEAREST

Singleton implementing nearest 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.

_name

private java.lang.String _name

The name of the rounding mode.

_nameToRounding

private static java.util.Map _nameToRounding

A map from rounding type name to the rounding type for all rounding types.

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.

_addRounding

static void _addRounding(Rounding type,
                         java.lang.String name)