The Overflow class provides a type safe enumeration of strategies for handling numeric overflows for FixPoint data types. Overflows are typically resolved after performing a FixPoint arithmetic operation or transformation.
The active class functionality is provided by the {@link #quantize(BigInteger,Precision) quantize} method. This methodevaluates an unscaled {@link BigInteger BigInteger} value and aPrecision constraint and creates a FixPoint object with a new unscaled value and precision that conforms to the corresponding overflow strategy. Depending on the overflow strategy used, the unscaled integer value or the precision may be changed as part of the overflow process.
The overflow strategies supported are as follows:
- grow
If the integer value does not fall within the dynamic range of the Precision constraint, increase the Precision to the minimum dynamic range needed to include the integerValue. Note that the actual integer unscaled value will not change during this overflow strategy. This rounding mode is supported by the static {@link #quantizeGrow(BigInteger,Precision) quantizeGrow} methodand the Overflow singletons {@link #GROW} and {@link #GENERAL}. - minimize
Represent the unscaled integer value with the minimum number of data bits. The sign and exponent of the new precision constraint is determined by the Precision parameter. The use of this overflow strategy may increase or decrease the Precision of the value. Note that the actual integer unscaled value will not change during this overflow strategy. This rounding mode is supported by the static {@link #quantizeMinimum(BigInteger,Precision) quantizeMinimize}method and the Overflow singleton {@link #MINIMIZE} . - modulo
This overflow strategy will perform a twos complement modulo operation any integer values that are outside of the dynamic range of the Precision constraint. Note that the actual precision will not change during this overflow strategy. This rounding mode is supported by the static {@link #quantizeModulo(BigInteger,Precision) quantizeModulo}method and the Overflow singletons {@link #MODULO} and {@link #WRAP}. - saturate
If the integer value falls outside of the Precision dynamic range, this overflow strategy will saturate result. If the value is below the minimum of the range, the minimum value of the range is used. If the value is above the maximum of the range, the maximum value of the range is used. Note that the precision will not change during this overflow strategy. This rounding mode is supported by the static {@link #quantizeSaturate(BigInteger,Precision) quantizeSaturate}method and the Overflow singletons {@link #SATURATE} and{@link #CLIP}. - to_zero
If the integer value falls outside of the Precision dynamic range, this overflow strategy will set the integer value to zero. Note that the actual precision will not change during this overflow strategy. This rounding mode is supported by the static {@link #quantizeToZero(BigInteger,Precision) quantizeToZero}method and the Overflow singleton {@link #TO_ZERO}. - trap
If the integer value falls outside of the Precision dynamic range, a {@link java.lang.ArithmeticException} is generated.This rounding mode is supported by the singleton {@link #TRAP}.
A specific strategy may be chosen dynamically by invoking {@link #forName forName} or {@link #getName getName}with one of the above strategy names. Alternatively a strategy may be selected by using one of the static singletons.
Division by zero can trigger the use of the plusInfinity or minusInfinity methods, which return null, except in the case of the to_zero and saturate strategies for which infinity is well-defined.
@author Ed Willink
@version $Id: Overflow.java,v 1.26 2007/12/07 06:30:34 cxh Exp $
@since Ptolemy II 2.1
@Pt.ProposedRating Red (Ed.Willink)
@Pt.AcceptedRating Red
@see ptolemy.math.FixPoint
@see ptolemy.math.Quantization
@see ptolemy.math.Rounding
