public class FixPoint
extends java.lang.Object
implements java.lang.Cloneable
The FixPoint class represents signed numbers in a two'scomplement
format or unsigned numbers in a binary format with unlimited dynamic
range and a resolution defined by a finite number of fractional bits.
The precision is defined by the
Precision
class.
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 an instance of
the Quantization
class.
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. To insure lossless operations, the resulting Precision of these operators will expand as necessary. Subsequent results can be quantized as necessary.
Violations of the lossless 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.
Precision
,
Quantization
Red 
Red (Ed.Willink) 
Modifier and Type  Class and Description 

static class 
FixPoint.Error
An instance of this class is used preserve backwards interface
compatibility.

Constructor and Description 

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

FixPoint(java.math.BigInteger unscaledIntegerValue,
Precision precision)
Construct a FixPoint from an unscaled integerValue that
with a given Precision constraint.

FixPoint(double doubleValue,
Quantization quant)
Construct a FixPoint from a double.

FixPoint(FixPoint fix,
Quantization quant)
Construct a new FixPoint object by requantizing the
given FixPoint object with a new quantization specification.

FixPoint(int intValue)
Construct a FixPoint from an integer.

FixPoint(int intValue,
boolean signed)
Construct a FixPoint from an integer.

FixPoint(int intValue,
Quantization quant)
Construct a FixPoint from an integer.

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

Modifier and Type  Method and Description 

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.

FixPoint 
add(FixPoint arg,
Quantization quant)
Return a FixPoint with a value equal to the sum of this
FixPoint and the argument.

static Precision 
addPrecision(Precision leftArgument,
Precision rightArgument)
Determines the Precision of an add operation between two
FixPoint values.

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)
Return a FixPoint with a value equal to the division of
this FixPoint by the argument.

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.

static Precision 
dividePrecision(Precision leftArgument,
Precision rightArgument)
Determines the Precision of a divide operation between
two FixPoint values.

double 
doubleValue()
Return the value of this FixPoint as a double.

boolean 
equals(java.lang.Object 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.

java.math.BigInteger 
getUnscaledValue()
Return the unscaled BigInteger value used to represent this
FixPoint value.

int 
hashCode()
Return a hash code value for this value.

FixPoint 
minimumQuantization()
Return a new FixPoint value that has the same value as this
FixPoint value but with the minimum quantization necessary for
representing the value.

FixPoint 
multiply(FixPoint arg)
Return a FixPoint with a value equal to the product of this
FixPoint and the argument.

FixPoint 
multiply(FixPoint arg,
Quantization quant)
Return a FixPoint with a value equal to the product of this
FixPoint and the argument.

static Precision 
multiplyPrecision(Precision leftArgument,
Precision rightArgument)
Determines the Precision of an multiply operation between
two FixPoint values.

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 with a value equal to the difference
between this FixPoint and the argument.

FixPoint 
subtract(FixPoint arg,
Quantization quant)
Return a FixPoint with a value equal to the difference of this
FixPoint and the argument.

static Precision 
subtractPrecision(Precision leftArgument,
Precision rightArgument)
Determines the Precision of an subtract operation between two
FixPoint values.

java.lang.String 
toBitString()
Return a bit string representation of this number.

java.lang.String 
toString()
Return a string representation of this number.

java.lang.String 
toStringPrecision()
Return a string representation of this number along with
the Precision of the number.

java.lang.String 
toStringValuePrecision()
Return a string representation of this number along with
the unscaled value and Precision of the number.

public FixPoint(java.math.BigDecimal bigDecimal, Quantization quant)
bigDecimal
 The floating point value.quant
 The quantization specification.public FixPoint(FixPoint fix, Quantization quant)
fix
 The existing FixPoint valuequant
 The quantization specification.public FixPoint(double doubleValue, Quantization quant)
doubleValue
 The floating point value.quant
 The quantization specification.java.lang.IllegalArgumentException
 If the doubleValue is equal
to Double.NEGATIVE_INFINITY, Double.POSITIVE_INFINITY,
or Double.NaN.public FixPoint(int intValue, Quantization quant)
intValue
 The integer value.quant
 The quantization specification.public FixPoint(int intValue)
intValue
 The integer value.public FixPoint(int intValue, boolean signed)
intValue
 The integer value.signed
 if true, represent value as a signed number;
otherwise represent value as an unsigned value.public FixPoint(java.lang.String string, Quantization quant)
string
 A string representation of the floating point value.quant
 The quantization specification.java.lang.IllegalArgumentException
 If string is not a valid
representation of a BigDecimal.FixPoint(java.math.BigInteger unscaledIntegerValue, Precision precision)
unscaledIntegerValue
 The integer value of the scaled
floating point value.precision
 The precision to represent the new unscaled value.java.lang.ArithmeticException
 when precision is not sufficient
to represent integerValue.
Note that this is package scopepublic static Precision addPrecision(Precision leftArgument, Precision rightArgument)
public static Precision subtractPrecision(Precision leftArgument, Precision rightArgument)
public static Precision multiplyPrecision(Precision leftArgument, Precision rightArgument)
public static Precision dividePrecision(Precision leftArgument, Precision rightArgument)
public FixPoint abs()
public FixPoint add(FixPoint arg)
arg
 The FixPoint addend.public FixPoint add(FixPoint arg, Quantization quant)
arg
 The FixPoint addend.quant
 The quantization specification.public java.math.BigDecimal bigDecimalValue()
public java.lang.Object clone()
clone
in class java.lang.Object
public FixPoint divide(FixPoint arg) throws java.lang.IllegalArgumentException
arg
 The FixPoint.divisor.java.lang.IllegalArgumentException
 If division by zero and
infinity not quantizable.public FixPoint divide(FixPoint arg, Quantization quant) throws java.lang.IllegalArgumentException
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.
arg
 The FixPoint.divisor.quant
 The quantization specification.java.lang.IllegalArgumentException
 If division by zero.public double doubleValue()
public boolean equals(java.lang.Object arg)
equals
in class java.lang.Object
arg
 The FixPoint object to use for equality
checking.@Deprecated public FixPoint.Error getError()
public Precision getPrecision()
public java.math.BigInteger getUnscaledValue()
public int hashCode()
hashCode
in class java.lang.Object
public FixPoint minimumQuantization()
public FixPoint multiply(FixPoint arg)
arg
 The FixPoint multiplier.public FixPoint multiply(FixPoint arg, Quantization quant)
arg
 The FixPoint multiplicand.quant
 The quantization specification.public void printFix()
public FixPoint quantize(Quantization quant)
FixPoint(FixPoint, Quantization)
.quant
 The quantization constraints.public FixPoint subtract(FixPoint arg)
arg
 The FixPoint subtrahend.public FixPoint subtract(FixPoint arg, Quantization quant)
arg
 The FixPoint addend.quant
 The quantization specification.public java.lang.String toBitString()
public java.lang.String toString()
toString
in class java.lang.Object
public java.lang.String toStringPrecision()
public java.lang.String toStringValuePrecision()