|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Objectptolemy.math.FixPoint
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.
Precision,
Quantization,
Serialized Form
| Red |
| 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 |
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(java.math.BigDecimal bigDecimal,
Quantization quant)
bigDecimal - The floating point value.quant - The quantization specification.
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.| Method Detail |
public FixPoint abs()
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!
public FixPoint add(FixPoint arg)
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!
arg - The FixPoint addend.
public java.math.BigDecimal bigDecimalValue()
public java.lang.Object clone()
public FixPoint divide(FixPoint arg)
throws java.lang.IllegalArgumentException
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!
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(FixPoint arg)
public FixPoint.Error getError()
public Precision getPrecision()
public int hashCode()
public FixPoint multiply(FixPoint arg)
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.
arg - The FixPoint multiplier.
public void printFix()
public FixPoint quantize(Quantization quant)
quant - The quantization constraints.
public FixPoint subtract(FixPoint arg)
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!
arg - The FixPoint subtrahend.
public java.lang.String toBitString()
public java.lang.String toString()
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||