Overflow

java.lang.Object
- ptolemy.math.Overflow

All Implemented Interfaces:

java.lang.Cloneable

Direct Known Subclasses:

Overflow.Grow, Overflow.Minimize, Overflow.Modulo, Overflow.Saturate, Overflow.ToZero, Overflow.Trap
```
public abstract class Overflow
extends java.lang.Object
implements java.lang.Cloneable
```
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 quantize method. This method evaluates an unscaled BigInteger value and a Precision 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 quantizeGrow method and the Overflow singletons GROW and 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 quantizeMinimize method and the Overflow singleton 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 quantizeModulo method and the Overflow singletons MODULO and 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 quantizeSaturate method and the Overflow singletons SATURATE and 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 quantizeToZero method and the Overflow singleton TO_ZERO.
- trap
  If the integer value falls outside of the Precision dynamic range, a ArithmeticException is generated. This rounding mode is supported by the singleton TRAP.
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.
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.
Since:

Ptolemy II 2.1

Version:

$Id$

Author:

Ed Willink

See Also:

FixPoint, Quantization, Rounding

Pt.AcceptedRating:

Red

Pt.ProposedRating:

Red (Ed.Willink)

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`Overflow.Grow` The grow overflow strategy.
`static class`	`Overflow.Minimize` The minimize overflow strategy.
`static class`	`Overflow.Modulo` The modulo overflow strategy.
`static class`	`Overflow.Saturate` The saturate overflows strategy.
`static class`	`Overflow.ToZero` The overflow to zero strategy.
`static class`	`Overflow.Trap` The trap overflows strategy.

Field Summary

Fields
Modifier and Type	Field and Description
`static Overflow.Saturate`	`CLIP` Singleton implementing Saturate overflow strategy.
`static Overflow.Grow`	`GENERAL` Singleton implementing Grow overflow strategy.
`static Overflow.Grow`	`GROW` Singleton implementing Grow overflow strategy.
`static Overflow.Minimize`	`MINIMIZE` Singleton implementing Minimize overflow strategy.
`static Overflow.Modulo`	`MODULO` Singleton implementing Modulo overflow strategy.
`static Overflow.Saturate`	`SATURATE` Singleton implementing Saturate overflow strategy.
`static Overflow.Trap`	`THROW` Singleton implementing Trap overflow strategy.
`static Overflow.ToZero`	`TO_ZERO` Singleton implementing to zero overflow strategy.
`static Overflow.Trap`	`TRAP` Singleton implementing Trap overflow strategy.
`static Overflow.Modulo`	`WRAP` Singleton implementing Modulo overflow strategy.

Constructor Summary

Constructors
Modifier Constructor and Description

protected Overflow(java.lang.String name)
Construct an Overflow object with the given String name.

Constructors
Modifier	Constructor and Description
`protected`	`Overflow(java.lang.String name)` Construct an Overflow object with the given String name.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`(package private) static void`	`_addOverflow(Overflow 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 Overflow as this object.
`static Overflow`	`forName(java.lang.String name)` Return an instance of this class with the specified name.
`static Overflow`	`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 boolean`	`isOutOfRange(java.math.BigInteger bigInt, Precision precision)` Determines whether the given BigInteger unscaled value is considered an "underflow" or an "overflow" under the given Precision constraint.
`static boolean`	`isOverflow(java.math.BigInteger value, Precision precision)` Determines whether the given BigInteger unscaled value is considered an "overflow" under the given Precision constraint.
`static boolean`	`isUnderflow(java.math.BigInteger bigInt, Precision precision)` Determines whether the given BigInteger unscaled value is considered an "underflow" under the given Precision constraint.
`java.math.BigInteger`	`minusInfinity(Quantization quant)` Return the value of minus infinity, or null if unrepresentable.
`static java.util.Iterator`	`nameIterator()` Return an iterator for the names of all overflow types.
`java.math.BigInteger`	`plusInfinity(Quantization quant)` Return the value of plus infinity, or null if unrepresentable.
`abstract FixPoint`	`quantize(java.math.BigInteger integerValue, Precision precision)` Return a new FixPoint object based on the given BigInteger value and Precision constraint.
`static FixPoint`	`quantizeGrow(java.math.BigInteger integerValue, Precision precision)` Quantize a FixPoint value using a "grow" overflow strategy.
`static FixPoint`	`quantizeMinimum(java.math.BigInteger bigInt, Precision p)` Generates a new FixPoint data value based on the unscaled value bigInt using as few bits as possible.
`static FixPoint`	`quantizeModulo(java.math.BigInteger integerValue, Precision precision)` Quantize a FixPoint value using a "modulo" overflow strategy.
`static FixPoint`	`quantizeSaturate(java.math.BigInteger integerValue, Precision precision)` Quantize a FixPoint value using a "saturate" overflow strategy.
`static FixPoint`	`quantizeToZero(java.math.BigInteger integerValue, Precision precision)` Quantize a FixPoint value using a "to Zero" overflow strategy.
`java.lang.String`	`toString()` Return the string representation of this overflow.

Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - GROW
```
public static final Overflow.Grow GROW
```
    Singleton implementing Grow overflow strategy.
  - MODULO
```
public static final Overflow.Modulo MODULO
```
    Singleton implementing Modulo overflow strategy.
  - MINIMIZE
```
public static final Overflow.Minimize MINIMIZE
```
    Singleton implementing Minimize overflow strategy.
  - TRAP
```
public static final Overflow.Trap TRAP
```
    Singleton implementing Trap overflow strategy.
  - SATURATE
```
public static final Overflow.Saturate SATURATE
```
    Singleton implementing Saturate overflow strategy.
  - TO_ZERO
```
public static final Overflow.ToZero TO_ZERO
```
    Singleton implementing to zero overflow strategy.
  - CLIP
```
public static final Overflow.Saturate CLIP
```
    Singleton implementing Saturate overflow strategy.
  - GENERAL
```
public static final Overflow.Grow GENERAL
```
    Singleton implementing Grow overflow strategy.
  - WRAP
```
public static final Overflow.Modulo WRAP
```
    Singleton implementing Modulo overflow strategy.
  - THROW
```
public static final Overflow.Trap THROW
```
    Singleton implementing Trap overflow strategy.
- Constructor Detail
  - Overflow
```
protected Overflow(java.lang.String name)
```
    Construct an Overflow object with the given String name. This name is used for finding an Overflow 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 Overflow 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 Overflow.
  - equals
```
public boolean equals(java.lang.Object object)
```
    Determine if the argument represents the same Overflow as this object.
    
    Overrides:
    
    equals in class java.lang.Object
    
    Parameters:
    
    object - Another object.
    
    Returns:
    
    True if the argument represents the same Overflow as this object; false otherwise.
  - forName
```
public static Overflow forName(java.lang.String name)
```
    Return an instance of this class with the specified name.
    
    Parameters:
    
    name - The name of the Overflow strategy to find.
    
    Returns:
    
    An instance of Overflow or null.
  - getName
```
public static Overflow 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 Overflow strategy to find.
    
    Returns:
    
    An instance of Overflow.
    
    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
  - isOutOfRange
```
public static boolean isOutOfRange(java.math.BigInteger bigInt,
                                   Precision precision)
```
    Determines whether the given BigInteger unscaled value is considered an "underflow" or an "overflow" under the given Precision constraint. This will occur if the value is less than the minimum unscaled value of the given Precision constraint or more than the maximum unscaled value of the given Precision constraint.
    
    Parameters:
    
    bigInt - The value to test for underflow.
    
    precision - The Precision constraint to use for the test.
    
    Returns:
    
    true if the value is considered an "underflow" or "overflow, false otherwise.
  - isOverflow
```
public static boolean isOverflow(java.math.BigInteger value,
                                 Precision precision)
```
    Determines whether the given BigInteger unscaled value is considered an "overflow" under the given Precision constraint. This will occur if the value is larger than the maximum unscaled value of the given Precision constraint. (@see Precision#getMaximumUnscaledValue())
    
    Parameters:
    
    value - The value to test for overflow.
    
    precision - The Precision constraint to use for the test.
    
    Returns:
    
    true if the value is considered an "overflow", false if it is not an "overflow".
  - isUnderflow
```
public static boolean isUnderflow(java.math.BigInteger bigInt,
                                  Precision precision)
```
    Determines whether the given BigInteger unscaled value is considered an "underflow" under the given Precision constraint. This will occur if the value is less than the minimum unscaled value of the given Precision constraint. (@see Precision#getMinimumUnscaledValue())
    
    Parameters:
    
    bigInt - The value to test for underflow.
    
    precision - The Precision constraint to use for the test.
    
    Returns:
    
    true if the value is considered an "underflow", false if it is not an "underflow".
  - 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.
  - minusInfinity
```
public java.math.BigInteger minusInfinity(Quantization quant)
```
    Return the value of minus infinity, or null if unrepresentable.
    The saturation value is returned for the saturate and to_zero strategies for which infinity is quantizable. Null is returned for other strategies.
    
    Parameters:
    
    quant - The quantization specification.
    
    Returns:
    
    The value if defined, null if not..
  - plusInfinity
```
public java.math.BigInteger plusInfinity(Quantization quant)
```
    Return the value of plus infinity, or null if unrepresentable.
    The saturation value is returned for the saturate and to_zero strategies for which infinity is quantizable. Null is returned for other strategies.
    
    Parameters:
    
    quant - The quantization specification.
    
    Returns:
    
    The value if defined, null if not.
  - quantize
```
public abstract FixPoint quantize(java.math.BigInteger integerValue,
                                  Precision precision)
```
    Return a new FixPoint object based on the given BigInteger value and Precision constraint. This method will return a valid FixPoint object that conforms to the given overflow strategy implemented by the extending class.
    
    Parameters:
    
    integerValue - The unbounded integer value.
    
    precision - The Precision constraint of the quantization.
    
    Returns:
    
    A valid FixPoint value that conforms to the overflow strategy.
  - quantizeGrow
```
public static FixPoint quantizeGrow(java.math.BigInteger integerValue,
                                    Precision precision)
```
    Quantize a FixPoint value using a "grow" overflow strategy. If the Precision format does not provide sufficient dynamic range for the value, 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.
    
    Parameters:
    
    integerValue - unscaled integer value to check for overflow
    
    precision - the precision constraint used for the overflow check
    
    Returns:
    
    Valid FixPoint data object
  - quantizeMinimum
```
public static FixPoint quantizeMinimum(java.math.BigInteger bigInt,
                                       Precision p)
```
    Generates a new FixPoint data value based on the unscaled value bigInt using as few bits as possible. The sign and exponent of the precision are obtained from the Precision parameter.
    
    Parameters:
    
    bigInt - Unscaled value to use for the FixPoint result
    
    p - Used to obtain the sign and exponent of the new FixPoint value.
    
    Returns:
    
    FixPoint value with as few bits as necessary.
  - quantizeModulo
```
public static FixPoint quantizeModulo(java.math.BigInteger integerValue,
                                      Precision precision)
```
    Quantize a FixPoint value using a "modulo" overflow strategy. If the unscaled integer value is outside of the dynamic range provided by the Precision constraint, modify the integer value to fit within the dynamic range using a modulo operation. Note that the Precision of the FixPoint value remains the same.
    
    Parameters:
    
    integerValue - unscaled integer value to check for overflow
    
    precision - the precision constraint used for the overflow check
    
    Returns:
    
    Valid FixPoint data object
  - quantizeSaturate
```
public static FixPoint quantizeSaturate(java.math.BigInteger integerValue,
                                        Precision precision)
```
    Quantize a FixPoint value using a "saturate" overflow strategy. If the unscaled integer value is outside of the dynamic range provided by the Precision constraint, modify the integer value to fit within the dynamic range by saturating the value to the maximum or minimum value supported by the Precision constraint. Note that the Precision of the FixPoint value remains the same.
    
    Parameters:
    
    integerValue - unscaled integer value to check for overflow
    
    precision - the precision constraint used for the overflow check
    
    Returns:
    
    Valid FixPoint data object
  - quantizeToZero
```
public static FixPoint quantizeToZero(java.math.BigInteger integerValue,
                                      Precision precision)
```
    Quantize a FixPoint value using a "to Zero" overflow strategy. If the unscaled integer value is outside of the dynamic range provided by the Precision constraint, set the integer value to zero. Note that the Precision of the FixPoint value remains the same.
    
    Parameters:
    
    integerValue - unscaled integer value to check for overflow
    
    precision - the precision constraint used for the overflow check
    
    Returns:
    
    Valid FixPoint data object
  - toString
```
public java.lang.String toString()
```
    Return the string representation of this overflow.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    A String.
  - _addOverflow
```
static void _addOverflow(Overflow type,
                         java.lang.String name)
```

Class Overflow

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

GROW

MODULO

MINIMIZE

TRAP

SATURATE

TO_ZERO

CLIP

GENERAL

WRAP

THROW

Constructor Detail

Overflow

Method Detail

clone

equals

forName

getName

hashCode

isOutOfRange

isOverflow

isUnderflow

nameIterator

minusInfinity

plusInfinity

quantize

quantizeGrow

quantizeMinimum

quantizeModulo

quantizeSaturate

quantizeToZero

toString

_addOverflow