ptolemy.math
Class Precision

java.lang.Object
  extended byptolemy.math.Precision
All Implemented Interfaces:
java.lang.Cloneable, java.io.Serializable

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

This class describes the precision of an instance of FixPoint. An instance of FixPoint represents a fixed point number as two finite bit sequences: an integer part and a fractional part. The total length of a fixed point value is the combined length of the integer part and the fractional part.

There are two string formats for precision, either of which is understood by the constructor that takes a string argument:

In both cases, the parentheses are optional.

The FixPoint class represents signed numbers in a 2's complement format. As a consequence, a single bit is used to represent the sign of the number. Therefore, when a precision is given of, for example, (6, 3), then 6 bits are used for the integer part and 3 are used for the fractional part. Of the 6 integer bits, 5 are used to represent a number and 1 is used for the sign.

In giving a precision, at least a single bit is required to describe the sign and thus the minimum precision that can be given to a FixPoint is equal to (1.0). Since a single bit is used, the FixPoint represents the numbers 0 and -1. Note that a precision of (2.0) represents the numbers 1, 0, -1, and -2. The representation is two's complement.

An instance of the class is immutable, meaning that its value is set in the constructor and cannot then be modified.

Since:
Ptolemy II 0.4
Version:
$Id: Precision.java,v 1.40 2004/04/13 03:45:46 cxh Exp $
Author:
Bart Kienhuis
See Also:
FixPoint, Serialized Form
Accepted Rating:
Red (kienhuis)
Proposed Rating:
Yellow (kienhuis)

Constructor Summary
Precision(int length, int integerBits)
          Construct a Precision object based on the provided numbers.
Precision(java.lang.String precision)
          Construct a Precision object based on the provided string.
 
Method Summary
 java.lang.Object clone()
          Return this, that is, return the reference to this object.
 boolean equals(java.lang.Object object)
          Return true if the indicated object is an instance of Precision and the number of integer and fractional bits both match.
 java.math.BigDecimal findMaximum()
          Return the maximum obtainable value in this precision.
 java.math.BigDecimal findMinimum()
          Return the minimum obtainable value for this precision.
 int getFractionBitLength()
          Return the number of bits representing the fractional part.
 int getIntegerBitLength()
          Return the number of bits representing the integer part.
 int getNumberOfBits()
          Return the total number of bits.
static Precision matchThePoint(Precision precisionA, Precision precisionB)
          Return the precision that is the maximum of the two supplied precisions in both the integer and fractional part.
 java.lang.String toString()
          Return a string representing this precision.
 
Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Precision

public Precision(java.lang.String precision)
          throws java.lang.IllegalArgumentException
Construct a Precision object based on the provided string. The string can describe the precision in either of the syntaxes explained in the description of this class.

Parameters:
precision - The string representing the precision.
Throws:
java.lang.IllegalArgumentException - If the precision string supplied does not match one of the known formats.

Precision

public Precision(int length,
                 int integerBits)
          throws java.lang.IllegalArgumentException
Construct a Precision object based on the provided numbers.

Parameters:
length - The total number of bits.
integerBits - The number of integer bits.
Throws:
java.lang.IllegalArgumentException - If the given values are negative or when the integer number of bits is larger than the total number of bits.
Method Detail

clone

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

Returns:
This Precision.

equals

public boolean equals(java.lang.Object object)
Return true if the indicated object is an instance of Precision and the number of integer and fractional bits both match.

Returns:
True if the precisions are equal.

findMaximum

public java.math.BigDecimal findMaximum()
Return the maximum obtainable value in this precision. When m represents the total number of bits and n the number of integer bits, this is equal to 2^(n-1) - 1/(2^(m-n)). NOTE: This method should be package friendly, not public. It is not intended to be used outside this package.

Returns:
The maximum value obtainable for this precision.

findMinimum

public java.math.BigDecimal findMinimum()
Return the minimum obtainable value for this precision. When m represents the total number of bits and n the number of integer bits, this is equal to -2^(n-1). NOTE: This method should be package friendly, not public. It is not intended to be used outside this package.

Returns:
The minimum value obtainable for the given precision..

getFractionBitLength

public int getFractionBitLength()
Return the number of bits representing the fractional part.

Returns:
The length of the fractional part.

getIntegerBitLength

public int getIntegerBitLength()
Return the number of bits representing the integer part.

Returns:
the length of the integer part.

getNumberOfBits

public int getNumberOfBits()
Return the total number of bits.

Returns:
the total number of bits.

matchThePoint

public static Precision matchThePoint(Precision precisionA,
                                      Precision precisionB)
Return the precision that is the maximum of the two supplied precisions in both the integer and fractional part. This method is used to align instances of FixPoint onto a single precision representation.

Parameters:
precisionA - A precision
precisionB - Another precision
Returns:
A precision at least as precise as the two arguments.

toString

public java.lang.String toString()
Return a string representing this precision. The string is expressed as "(m.n)", where m indicates the number of integer bits and n represents the number of fractional bits.

Returns:
A string representing this precision.