java.lang.Object
- ptolemy.math.Precision

All Implemented Interfaces:: java.lang.Cloneable

public class Precision
extends java.lang.Object
implements java.lang.Cloneable

This class defines the precision of a signed or unsigned fixed point value. The precision of a fixed point value is represented as internally as three fields: the number of bits (n), the binary exponent (e), and a sign bit (s). The number of bits (n) defines the dynamic range of the format (2ⁿ). The exponent (e) determines the placement of the binary point for all values of this format. This binary point placement is "fixed" and is specified within the precision format rather than within individual Fixed point values. The mantissa bits of all fixed point values using this this precision format are multiplied by 2^m. Note that m can take on a positive, negative, or zero value. This allows the binary point to be placed anywhere necessary and even beyond the bounds of the mantissa (i.e. to the right of the lsb or to the left of the msb). The sign value s is used to indicate whether the fixed point precision value is treated as signed (s = 1) or unsigned (s = 0).

Signed fixed point formats are represented in a 2's complement format. As a consequence, a single bit is used to represent the sign of the number. The value of a multi-bit signed number is:

Signed(B) = 2^m x (- b_{n-1} x 2^{n-1} + \sum_{i=0}^{n-2} b_i x 2^i), where b_i is the value of bit i of the bit vector.

Unsigned fixed formats are represented as unsigned binary values. No bits are used to represent the sign and all values are positive. The actual value of a multi-bit unsigned fixed point number is:

Unsigned(B) = 2^m x (\sum_{i=0}^{n-1} b_i x 2^i)

This class supports several different String formats for specifying and displaying the Precision. These String formats are supported by several classes that extend the Precision.PrecisionFormat class. Several such classes have been created. Any given precision string format can be represented in any of the valid precision string formats. The four supported Precision String formats are shown in the table below. A static singleton object of each of these formats is provided in this class. Each String Representation column of the table represent equivalent Precision formats:

Precision Formats.
Format Name	Format Spec	String Representation
`Precision.IntegerFractionPrecisionFormat`	[integer bits].[fraction bits]	3.2	0.7	-2.12	12.-4	32.0	U1.7
`Precision.LengthIntegerPrecisionFormat`	[total bits]/[integer bits]	5/3	7/0	10/-2	8/12	32/32	U8/1
`Precision.VHDLPrecisionFormat`	[MSb position]:[LSb position]	2:-2	-1:-7	-3:-12	11:4	31:0	U0:-7
`Precision.LengthExponentPrecisionFormat`	[total bits]e[binary point position]	5e-2	7e-7	10e-12	8e4	32e0	U8e-7

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$
Author:: Bart Kienhuis, Contributor: Mike Wirthlin
See Also:: FixPoint
Pt.AcceptedRating:: Red (kienhuis)
Pt.ProposedRating:: Yellow (kienhuis)

Nested Class Summary

Nested Classes
Modifier and Type	Class	Description
`static class`	`Precision.ExpressionLanguagePrecisionFormat`	Precision format for use with the Expression Language.
`static class`	`Precision.IntegerFractionPrecisionFormat`	Defines a Precision string format using the INTEGER.FRACTION precision format.
`static class`	`Precision.LengthExponentPrecisionFormat`	Defines a Precision string format using the LENGTHeEXPONENT precision format.
`static class`	`Precision.LengthIntegerPrecisionFormat`	Defines a Precision string format using the LENGTH/INTEGER precision format.
`static class`	`Precision.PrecisionFormat`	Defines a String format for specifying a Precision object.
`static class`	`Precision.VHDLPrecisionFormat`	Defines a Precision string format using the VHDL MSB:LSB precision format.

Field Summary

Fields
Modifier and Type	Field	Description
`static Precision.PrecisionFormat`	`EXPRESSION_LANGUAGE`	static ExpressionLanguagePrecisionFormat object.
`static Precision.PrecisionFormat`	`INTEGER_FRACTION`	static IntegerFractionPrecisionFormat object.
`static Precision.PrecisionFormat`	`LENGTH_EXPONENT`	static LengthExponentPrecisionFormat object.
`static Precision.PrecisionFormat`	`LENGTH_INTEGER`	static LengthIntegerPrecisionFormat object.
`static Precision.PrecisionFormat`	`VHDL`	static VHDLPrecisionFormat object.

Constructor Summary

Constructors
Constructor	Description
`Precision(int length, int integerBits)`	Construct a Precision object based on the length/integer bits format.
`Precision(int sign, int length, int exponent)`	Construct a Precision object based on the sign, length, and exponent format.
`Precision(java.lang.String str)`	Construct a Precision object based on the provided string.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`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 precision format matches exactly.
`java.math.BigDecimal`	`findMaximum()`	Return the maximum obtainable value in this precision.
`java.math.BigDecimal`	`findMinimum()`	Return the minimum obtainable value for this precision.
`java.math.BigDecimal`	`getEpsilon()`	Return the incremental value between discrete values under the given Precision format.
`int`	`getExponent()`	Return the location of the binary exponent.
`int`	`getFractionBitLength()`	Return the number of bits representing the fractional part.
`int`	`getIntegerBitLength()`	Return the number of bits representing the integer part.
`int`	`getLeastSignificantBitPosition()`	Return the bit position of the least significant bit of the given fixed point precision.
`java.math.BigInteger`	`getMaximumUnscaledValue()`	Return the maximum integer value before scaling so that quantization levels are represented by adjacent integers.
`java.math.BigInteger`	`getMinimumUnscaledValue()`	Return the minimum integer value before scaling so that quantization levels are represented by adjacent integers.
`int`	`getMostSignificantBitPosition()`	Return the bit position of the most significant bit of the given fixed point precision.
`int`	`getMostSignificantDataBitPosition()`	Return the bit position of the most significant data bit of the given fixed point precision.
`int`	`getNumberOfBits()`	Return the total number of bits.
`java.math.BigInteger`	`getNumberOfLevels()`	Return the total number of discrete values possible.
`int`	`getSign()`	Return the sign (0 = unsigned, 1 = signed).
`int`	`hashCode()`	Return a hash code value for this Precision.
`boolean`	`isSigned()`	Determine if the fixed point format is signed or not.
`static java.math.BigDecimal`	`shiftBigDecimal(java.math.BigDecimal val, int shiftval)`	Shift the BigDecimal value either right or left by a power of 2 value.
`java.lang.String`	`toString()`	Return a string representing this precision.
`java.lang.String`	`toString(Precision.PrecisionFormat format)`	Return a string representation of this format in one of several styles.
`static Precision`	`union(Precision precisionA, Precision precisionB)`	Return the precision that is the maximum of the two supplied precisions in both the length and exponent.

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

- Field Detail
  - INTEGER_FRACTION
```
public static final Precision.PrecisionFormat INTEGER_FRACTION
```
    static IntegerFractionPrecisionFormat object.
  - LENGTH_EXPONENT
```
public static final Precision.PrecisionFormat LENGTH_EXPONENT
```
    static LengthExponentPrecisionFormat object.
  - LENGTH_INTEGER
```
public static final Precision.PrecisionFormat LENGTH_INTEGER
```
    static LengthIntegerPrecisionFormat object.
  - EXPRESSION_LANGUAGE
```
public static final Precision.PrecisionFormat EXPRESSION_LANGUAGE
```
    static ExpressionLanguagePrecisionFormat object.
  - VHDL
```
public static final Precision.PrecisionFormat VHDL
```
    static VHDLPrecisionFormat object.
- Constructor Detail
  - Precision
```
public Precision(java.lang.String str)
          throws java.lang.IllegalArgumentException
```
    Construct a Precision object based on the provided string. The string can describe the precision in any of the syntaxes explained in the description of this class.
    
    Parameters:
    
    str - 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 length/integer bits format. This constructor will create a new signed Precision object with length bits and an exponent of -fracBits.
    
    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.
  - Precision
```
public Precision(int sign,
                 int length,
                 int exponent)
          throws java.lang.IllegalArgumentException
```
    Construct a Precision object based on the sign, length, and exponent format.
    
    Parameters:
    
    sign - The presence of a sign bit (1 = signed, 0 = unsigned).
    
    length - The total number of bits.
    
    exponent - The bit location of the exponent.
    
    Throws:
    
    java.lang.IllegalArgumentException - If the Precision arguments are inconsistent.
- 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 Precision.
  - equals
```
public boolean equals(java.lang.Object object)
```
    Return true if the indicated object is an instance of Precision and the precision format matches exactly.
    
    Overrides:
    
    equals in class java.lang.Object
    
    Parameters:
    
    object - Object to test for equality
    
    Returns:
    
    True if the precisions are equal.
  - findMaximum
```
public java.math.BigDecimal findMaximum()
```
    Return the maximum obtainable value in this precision. This value is obtained by multiplying the result of getMaximumUnscaledValue() by 2^exponent.
    
    Returns:
    
    The maximum value obtainable for this precision.
  - findMinimum
```
public java.math.BigDecimal findMinimum()
```
    Return the minimum obtainable value for this precision. This value is obtained by multiplying the result of getMinimumUnscaledValue() by 2^exponent.
    
    Returns:
    
    The minimum value obtainable for the given precision.
  - getEpsilon
```
public java.math.BigDecimal getEpsilon()
```
    Return the incremental value between discrete values under the given Precision format. This is calculated as 2^exponent.
    
    Returns:
    
    Incremental (epsilon) value.
  - getExponent
```
public int getExponent()
```
    Return the location of the binary exponent.
    
    Returns:
    
    the location of the fixed binary exponent.
  - getFractionBitLength
```
public int getFractionBitLength()
```
    Return the number of bits representing the fractional part. The is computed as -exponent.
    
    Returns:
    
    The length of the fractional part.
  - getIntegerBitLength
```
public int getIntegerBitLength()
```
    Return the number of bits representing the integer part. This is computed as length + exponent.
    
    Returns:
    
    the length of the integer part.
  - getLeastSignificantBitPosition
```
public int getLeastSignificantBitPosition()
```
    Return the bit position of the least significant bit of the given fixed point precision. This value is the same as the exponent value of this format. Bit 0 refers to the bit just to the left of the binary point.
    
    Returns:
    
    Least significant bit position.
  - getMaximumUnscaledValue
```
public java.math.BigInteger getMaximumUnscaledValue()
```
    Return the maximum integer value before scaling so that quantization levels are represented by adjacent integers. For signed values, this number is 2^(n-1) - 1 For unsigned values, this number is 2^(n) - 1
    
    Returns:
    
    The maximum inclusive value.
  - getMinimumUnscaledValue
```
public java.math.BigInteger getMinimumUnscaledValue()
```
    Return the minimum integer value before scaling so that quantization levels are represented by adjacent integers. For signed values, this number is -(2^(n-1)) For unsigned values, this number is 0.
    
    Returns:
    
    The minimum unscaled value value obtainable for the given precision.
  - getMostSignificantBitPosition
```
public int getMostSignificantBitPosition()
```
    Return the bit position of the most significant bit of the given fixed point precision. Bit 0 refers to the bit just to the left of the binary point.
    
    Returns:
    
    Least significant bit position.
  - getMostSignificantDataBitPosition
```
public int getMostSignificantDataBitPosition()
```
    Return the bit position of the most significant data bit of the given fixed point precision. If this Precision is signed, this will return getMostSignificantBitPosition - 1. If this Precision is unsigned, this will return getMostSignificantBitPosition.
    
    Returns:
    
    Least significant bit position.
  - getNumberOfBits
```
public int getNumberOfBits()
```
    Return the total number of bits.
    
    Returns:
    
    the total number of bits.
  - getNumberOfLevels
```
public java.math.BigInteger getNumberOfLevels()
```
    Return the total number of discrete values possible.
    
    Returns:
    
    the total number of levels.
  - getSign
```
public int getSign()
```
    Return the sign (0 = unsigned, 1 = signed).
    
    Returns:
    
    the sign status.
  - hashCode
```
public int hashCode()
```
    Return a hash code value for this Precision. This method returns the bitwise and of the length, exponent and sign.
    
    Overrides:
    
    hashCode in class java.lang.Object
    
    Returns:
    
    A hash code value for this Precision.
  - isSigned
```
public boolean isSigned()
```
    Determine if the fixed point format is signed or not.
    
    Returns:
    
    true if format is signed
  - union
```
public static Precision union(Precision precisionA,
                              Precision precisionB)
```
    Return the precision that is the maximum of the two supplied precisions in both the length and exponent. This method is used to align instances of FixPoint onto a single precision representation. If either Precision object is signed, the new Precision object will be signed.
    
    Parameters:
    
    precisionA - A precision
    
    precisionB - Another precision
    
    Returns:
    
    A precision at least as precise as the two arguments.
  - shiftBigDecimal
```
public static java.math.BigDecimal shiftBigDecimal(java.math.BigDecimal val,
                                                   int shiftval)
```
    Shift the BigDecimal value either right or left by a power of 2 value. This method will perform a multiplication by 2^^shiftval on the BigDecimal value when shiftval is positive and will perform a divide by 2^^-shiftval on the BigDecimal value when shiftval is negative.
    
    Parameters:
    
    val - BigDecimal value to shift.
    
    shiftval - Amount of "power of 2" shifting to perform on the BigDecimal value
    
    Returns:
    
    shifted BigDecimal value.
  - 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.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    A string representing this precision.
  - toString
```
public java.lang.String toString(Precision.PrecisionFormat format)
```
    Return a string representation of this format in one of several styles.
    
    Parameters:
    
    format - The String format represented desired for printing.
    
    Returns:
    
    String representation of the object using the given PrecisionFormat

Class Precision

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

INTEGER_FRACTION

LENGTH_EXPONENT

LENGTH_INTEGER

EXPRESSION_LANGUAGE

VHDL

Constructor Detail

Precision

Precision

Precision

Method Detail

clone

equals

findMaximum

findMinimum

getEpsilon

getExponent

getFractionBitLength

getIntegerBitLength

getLeastSignificantBitPosition

getMaximumUnscaledValue

getMinimumUnscaledValue

getMostSignificantBitPosition

getMostSignificantDataBitPosition

getNumberOfBits

getNumberOfLevels

getSign

hashCode

isSigned

union

shiftBigDecimal

toString

toString