ptolemy.math
Class Overflow

java.lang.Object
  extended byptolemy.math.Overflow
All Implemented Interfaces:
java.lang.Cloneable, java.io.Serializable
Direct Known Subclasses:
Overflow.General, Overflow.Grow, Overflow.Modulo, Overflow.Saturate, Overflow.ToZero, Overflow.Trap, Overflow.Unknown

public abstract class Overflow
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable

The Overflow class provides a type safe enumeration of strategies for handling numeric overflows. Overflows are 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.

The overflow strategies are

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 active class functionality is provided by the quantize method which is normally invoked from Quantization.quantize.

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: Overflow.java,v 1.10 2004/04/13 03:45:44 cxh Exp $
Author:
Ed Willink
See Also:
FixPoint, Quantization, Rounding, Serialized Form
Accepted Rating:
Red
Proposed Rating:
Red (Ed.Willink)

Nested Class Summary
static class Overflow.General
          The general overflow strategy at the top of the overflow lattice
static class Overflow.Grow
          The grow 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
static class Overflow.Unknown
          The unknown overflow strategy at the bottom of the overflow lattice
 
Field Summary
static Overflow.Saturate CLIP
           
static Overflow.General GENERAL
           
static Overflow.Grow GROW
           
static Overflow.Modulo MODULO
           
static Overflow.Saturate SATURATE
           
static Overflow.Trap THROW
           
static Overflow.ToZero TO_ZERO
           
static Overflow.Trap TRAP
           
static Overflow.Unknown UNKNOWN
           
static Overflow.Modulo WRAP
           
 
Constructor Summary
protected Overflow(java.lang.String name)
           
 
Method Summary
 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.
 java.math.BigInteger minusInfinity(Quantization quant)
          Return the value of minus infinity, or null if unrepresentable.
 java.math.BigInteger plusInfinity(Quantization quant)
          Return the value of plus infinity, or null if unrepresentable.
abstract  java.math.BigInteger quantize(java.math.BigInteger integerValue, Quantization quant)
          Return the integerValue after applying the overflow constraints of quant.
 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

GENERAL

public static final Overflow.General GENERAL

GROW

public static final Overflow.Grow GROW

MODULO

public static final Overflow.Modulo MODULO

WRAP

public static final Overflow.Modulo WRAP

SATURATE

public static final Overflow.Saturate SATURATE

CLIP

public static final Overflow.Saturate CLIP

TO_ZERO

public static final Overflow.ToZero TO_ZERO

TRAP

public static final Overflow.Trap TRAP

THROW

public static final Overflow.Trap THROW

UNKNOWN

public static final Overflow.Unknown UNKNOWN
Constructor Detail

Overflow

protected Overflow(java.lang.String name)
Method Detail

clone

public java.lang.Object clone()
Return this, that is, return the reference to this object.

Returns:
This Overflow.

equals

public boolean equals(java.lang.Object object)
Determine if the argument represents the same Overflow as this 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.

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.

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.


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 java.math.BigInteger quantize(java.math.BigInteger integerValue,
                                              Quantization quant)
Return the integerValue after applying the overflow constraints of quant.

Parameters:
integerValue - The unbounded integer value.
quant - The quantization constraints.
Returns:
The bounded integer value.

toString

public java.lang.String toString()
Return the string representation of this overflow.

Returns:
A String.