ptolemy.math
Class FixPoint

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

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

The FixPoint class provides a fixed point data type and a set of functions that operate on and return fixed point data. An instance of the class is immutable, meaning that its value is set in the constructor and cannot then be modified. This is similar to the Java built-in classes like Double, Integer, etc.

The FixPoint class represents signed numbers in a two's-complement format with unlimited dynamic range and a resolution defined by a finite number of fractional bits.

Because a fixed point data type uses a finite number of bits to represent a value, a real value is converted to a number that can be expressed with a given precision of the fixed point, thereby introducing a quantization error. The overflow and rounding strategies used for this quantization are defined by a Quantization instance.

The design of the FixPoint class complies with a philosophy that all operators work losslessly, i.e. the fractional precision of the result is determined such there is no loss of precision. These changes are different for the various operations.

Violations of the loss-less philosophy occur during construction, division and conversion to floating point. During construction from floating point values, the nearest fixed point representation is created. The preferred divide operator provides for explicit specification of the quantization. A deprecated divide operator guesses at the result precision. Conversion to floating point is limited by the available floating point accuracy.

The FixPoint implementation uses the Java class BigInteger to represent the finite value and so this implementation is truly platform independent. Note that the FixPoint does not put any restrictions on the maximum number of bits in the representation of a value.

Since:
Ptolemy II 0.4, rewritten for Ptolemy II 2.2
Version:
$Id: FixPoint.java,v 1.60 2004/04/13 03:45:10 cxh Exp $
Author:
Bart Kienhuis, Ed Willink, Contributor: Edward A. Lee
See Also:
Precision, Quantization, Serialized Form
Accepted Rating:
Red
Proposed Rating:
Red (Ed.Willink)

Nested Class Summary
static class FixPoint.Error
          An instance of this class is used preserve backwards interface compatibility.
 
Constructor Summary
FixPoint(java.math.BigDecimal bigDecimal, Quantization quant)
          Construct a FixPoint by converting a bigDecimal to comply with a quantization specification.
FixPoint(double doubleValue, Quantization quant)
          Construct a FixPoint by converting a double to comply with a quantization specification.
FixPoint(java.lang.String string, Quantization quant)
          Construct a FixPoint by converting the BigDecimal interpretation of a string to comply with a quantization specification.
 
Method Summary
 FixPoint abs()
          Return a FixPoint with a value equal to the absolute value of this FixPoint.
 FixPoint add(FixPoint arg)
          Return a FixPoint with a value equal to the sum of this FixPoint and the argument.
 java.math.BigDecimal bigDecimalValue()
          Return the value of this FixPoint as a BigDecimal number.
 java.lang.Object clone()
          Return this, that is, return the reference to this object.
 FixPoint divide(FixPoint arg)
          Deprecated. Use divide(FixPoint arg, Quantization quant).
 FixPoint divide(FixPoint arg, Quantization quant)
          Return a FixPoint equal to the division of this FixPoint by the argument, after application of a quantization specification to the result.
 double doubleValue()
          Return the value of this FixPoint as a double.
 boolean equals(FixPoint arg)
          Return true if this FixPoint is equal to the argument.
 FixPoint.Error getError()
          Deprecated. Overflow and rounding status no longer form part of the functionality. Use an overflow and rounding mode that gives the required behaviour or use Overflow.TRAP and/or Rounding.UNNECESSARY to throw exceptions if external interaction is required.
 Precision getPrecision()
          Return a precision to represent this number.
 int hashCode()
          Return a hash code value for this value.
 FixPoint multiply(FixPoint arg)
          Return a FixPoint number with a value equal to the product of this number and the argument.
 void printFix()
          Print useful debug information about the FixPoint to standard out.
 FixPoint quantize(Quantization quant)
          Return the value after conversion to comply with a quantization specification.
 FixPoint subtract(FixPoint arg)
          Return a FixPoint number with a value equal to this number minus the argument.
 java.lang.String toBitString()
          Return a bit string representation of this number.
 java.lang.String toString()
          Return a string representation of this number.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

FixPoint

public FixPoint(double doubleValue,
                Quantization quant)
Construct a FixPoint by converting a double to comply with a quantization specification.

Parameters:
doubleValue - The floating point value.
quant - The quantization specification.
Throws:
java.lang.IllegalArgumentException - If the doubleValue is equal to Double.NEGATIVE_INFINITY, Double.POSITIVE_INFINITY, or Double.NaN.

FixPoint

public FixPoint(java.math.BigDecimal bigDecimal,
                Quantization quant)
Construct a FixPoint by converting a bigDecimal to comply with a quantization specification.

Parameters:
bigDecimal - The floating point value.
quant - The quantization specification.

FixPoint

public FixPoint(java.lang.String string,
                Quantization quant)
Construct a FixPoint by converting the BigDecimal interpretation of a string to comply with a quantization specification.

Parameters:
string - A string representation of the floating point value.
quant - The quantization specification.
Throws:
java.lang.IllegalArgumentException - If string is not a valid representation of a BigDecimal.
Method Detail

abs

public FixPoint abs()
Return a FixPoint with a value equal to the absolute value of this FixPoint. The operation is lossless.

The fractional precision of the result is equal to the fractional precision of the input.

The integer precision annotation of the result is equal to the the integer precision annotation of the input!

Returns:
A non-negative fixed point.

add

public FixPoint add(FixPoint arg)
Return a FixPoint with a value equal to the sum of this FixPoint and the argument. The operation is lossless.

The fractional precision of the result is equal to the maximum of the fractional precisions of the inputs.

The integer precision annotation of the result is equal to the maximum of the integer precision annotations of the inputs!

Parameters:
arg - The FixPoint addend.
Returns:
The FixPoint sum.

bigDecimalValue

public java.math.BigDecimal bigDecimalValue()
Return the value of this FixPoint as a BigDecimal number. This is lossless, since the scale of the BigDecimal is set to the number of fractional bits.

Returns:
The BigDecimal value of this FixPoint.

clone

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

Returns:
This XixPoint.

divide

public FixPoint divide(FixPoint arg)
                throws java.lang.IllegalArgumentException
Deprecated. Use divide(FixPoint arg, Quantization quant).

Return a FixPoint with a value equal to the division of this FixPoint by the argument. The operation is not lossless.

The fractional precision of the result is equal to the maximum of the fractional precision of the divisor and dividend. Thus when a number with 3 fractional bits is divided by a FixPoint with 4 fractional bits, the resulting FixPoint will be rounded to 4 fractional bits.

The integer precision annotation of the result is equal to the maximum of the integer precision annotations of the inputs!

Parameters:
arg - The FixPoint.divisor.
Returns:
The FixPoint quotient.
Throws:
java.lang.IllegalArgumentException - If division by zero and infinity not quantizable.

divide

public FixPoint divide(FixPoint arg,
                       Quantization quant)
                throws java.lang.IllegalArgumentException
Return a FixPoint equal to the division of this FixPoint by the argument, after application of a quantization specification to the result. The operation is not lossless.

Division by zero results in a value of plus or minus infinity, which throws an exception if the overflow strategy defined by the quantization specification returns null for plusInfinity or minusInfinity.

Parameters:
arg - The FixPoint.divisor.
quant - The quantization specification.
Returns:
The FixPoint quotient.
Throws:
java.lang.IllegalArgumentException - If division by zero.

doubleValue

public double doubleValue()
Return the value of this FixPoint as a double. This is not necessarily lossless, since the precision of the fixed point number may exceed that of the double.

Returns:
The double value of this FixPoint.

equals

public boolean equals(FixPoint arg)
Return true if this FixPoint is equal to the argument. Two FixPoints are considered equal when the two values are precisely the same. The two FixPoints need not therefore have the same number of fraction bits, but any additional fractional bits in one value must be zero in the other.

Returns:
True if the FixPoints are equal; false otherwise.

getError

public FixPoint.Error getError()
Deprecated. Overflow and rounding status no longer form part of the functionality. Use an overflow and rounding mode that gives the required behaviour or use Overflow.TRAP and/or Rounding.UNNECESSARY to throw exceptions if external interaction is required.

Get the Error condition from the FixValue.

Returns:
The error condition of the FixValue.

getPrecision

public Precision getPrecision()
Return a precision to represent this number. This is constructed from the necessary fraction precision and the integer precision annotation.

Returns:
The Precision of this number.

hashCode

public int hashCode()
Return a hash code value for this value. This method returns the low order 32 bits of the integer representation.

Returns:
A hash code value for this value.

multiply

public FixPoint multiply(FixPoint arg)
Return a FixPoint number with a value equal to the product of this number and the argument. The operation is lossless.

The fractional precision of the result is equal to the sum of the fractional precisions of the inputs. The integer precision of the result is equal to the sum of the integer precisions of the inputs.

Parameters:
arg - The FixPoint multiplier.
Returns:
The FixPoint product.

printFix

public void printFix()
Print useful debug information about the FixPoint to standard out. This is used for debugging.


quantize

public FixPoint quantize(Quantization quant)
Return the value after conversion to comply with a quantization specification.

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

subtract

public FixPoint subtract(FixPoint arg)
Return a FixPoint number with a value equal to this number minus the argument. The operation is lossless.

The fractional precision of the result is equal to the maximum of the fractional precisions of the inputs.

The integer precision annotation of the result is equal to the maximum of the integer precision annotations of the inputs!

Parameters:
arg - The FixPoint subtrahend.
Returns:
The FixPoint difference.

toBitString

public java.lang.String toBitString()
Return a bit string representation of this number. The string takes the form "sign integerBits . fractionBits", where sign is - or nothing, integerBits and fractionBits are each a sequence of "0" and "1". integerBits comprises no leading zeroes. fractionBits has exactly one digit per bit. If the fixed point number has zero or negative number of fraction bits, the dot is omitted.

Returns:
A binary string representation of the value.

toString

public java.lang.String toString()
Return a string representation of this number. This is calculated by first converting the number to a BigDecimal, and then returning its string representation. In order to avoid loss there may be as many decimal digits following the decimal point as there fractional bits in this FixPoint.

Returns:
A decimal string representation of the value.