com.dautelle.math.numbers
Class Real

java.lang.Object
  java.lang.Number
      com.dautelle.math.numbers.RealtimeNumber
          com.dautelle.math.numbers.Real

All Implemented Interfaces:

java.lang.Comparable, Operable, Realtime, Representable, java.io.Serializable

public final class Real

extends RealtimeNumber

implements java.lang.Comparable

This class represents a real number of arbitrary precision with known/guaranteed uncertainty. A real number consists of a mantissa, a maximum error (on the mantissa) and a decimal exponent: ((mantissa ± error) · 10exponent).

The decimal representations of real instances are indicative of their precision as only digits guaranteed to be exact are written out. For example, the string "2.000" represents a real value of (2.0 ± 0.001). The precision or accuracy of any real number is available and guaranteed (the true/exact value is always within the precision/accuracy range).

Operations on instances of this class are quite fast as information substantially below the precision level (aka noise) is not processed/stored. There is no limit on a real precision but precision degenerates (due to numeric errors) and calculations accelerate as more and more operations are performed.

Instances of this class can be utilized to find approximate solutions to linear equations using the Matrix class for which high-precision reals is often required, the primitive type double being not accurate enough to resolve equations when the matrix's size exceeds 100x100. Furthermore, even for small matrices the "qualified" result is indicative of possible system singularities.

Version:

6.0, June 19, 2004

Author:

Jean-Marie Dautelle

See Also:

Serialized Form

Nested Class Summary

static class

Real.Value This inner class represents a mutable image of an immutable Real.

Nested classes inherited from class com.dautelle.math.numbers.RealtimeNumber

RealtimeNumber.Factory

Field Summary

static Real

NaN Holds a Not-a-Number instance (infinite error).

Method Summary

Real	abs() Returns the absolute value of this real number.
Real	add(Real that) Returns the sum of this real number with the one specified.
java.lang.StringBuffer	appendTo(java.lang.StringBuffer sb) Appends the decimal text representation of this real number to the StringBuffer argument.
boolean	approxEquals(Real that) Indicates if this real is approximately equals to the one specified.
int	compareTo(java.lang.Object that) Compares two real numbers numerically.
Real	divide(Real that) Returns this real number divided by the one specified.
double	doubleValue() Returns the value of this real number as a double.
boolean	equals(java.lang.Object that) Compares this real number against the specified object.
java.lang.Object	export() Exports this object out of the current pool context.
float	floatValue() Returns the value of this real number as a float.
int	getAccuracy() Returns the number of decimal digits guaranteed exact which appear to the right of the decimal point (absolute error).
LargeInteger	getError() Returns the maximum error (positive) on this real's mantissa.
int	getExponent() Returns the exponent of the power of 10 multiplier.
LargeInteger	getMantissa() Returns this real's mantissa.
int	getPrecision() Returns the total number of decimal digits guaranteed exact (relative error).
int	hashCode() Returns the hash code for this real number.
int	intValue() Returns the value of this real number as an int.
Real	inverse() Returns the inverse of this real number.
boolean	isNaN() Indicates if this real is Not-a-Number (unbounded value interval).
boolean	isNegative() Indicates if this real is less than zero.
boolean	isPositive() Indicates if this real is greater than zero.
long	longValue() Returns the value of this real number as a long.
Real	multiply(Real that) Returns the product of this real number with the one specified.
Real	negate() Returns the negation of this real number.
Operable	opposite() Returns the additive inverse of this object.
Operable	plus(Operable that) Returns the sum of this object with the one specified.
Operable	reciprocal() Returns the multiplicative inverse of this object.
static void	setIntegerAccuracy(int accuracy) Sets the local number of decimal zeros in the fraction part for reals created from integer values (default 18 zeros).
Real	subtract(Real that) Returns the difference between this real number and the one specified.
Operable	times(Operable that) Returns the product of this object with the one specified.
java.lang.Object	toHeap() Moves this object to the heap.
LargeInteger	toLargeInteger() Converts this real to a LargeInteger instance.
java.lang.String	toString() Returns the decimal text representation of this real number.
void	toXml(XmlElement xml) Sets the attributes and content of the XML element corresponding to this object.
static Real	valueOf(java.lang.CharSequence chars) Returns the real for the specified character sequence.
static Real	valueOf(double doubleValue) Converts a double value to a real instance.
static Real	valueOf(LargeInteger integer) Converts an integer value to a real instance.
static Real	valueOf(LargeInteger mantissa, LargeInteger error, int exponent) Returns a real having the specified mantissa, error and exponent values.
static Real	valueOf(long integer) Converts an integer value to a real instance.
static Real	valueOf(XmlElement xml) XML factory method.

Methods inherited from class com.dautelle.math.numbers.RealtimeNumber

clone, isLocalObject, isPoolObject, pow, recycle

Methods inherited from class java.lang.Number

byteValue, shortValue

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

NaN

public static final Real NaN

Holds a Not-a-Number instance (infinite error).

Method Detail

valueOf

public static Real valueOf(LargeInteger mantissa,
                           LargeInteger error,
                           int exponent)

Returns a real having the specified mantissa, error and exponent values. For example:

     // x = 0.0 ± 0.01  ("0.00" or "0E-2")
     Real x = Real.valueOf(LargeInteger.ZERO,
                           LargeInteger.ONE, -2);

      // y = -12.3 ± 0.005 ("-12300±5E-3") 
     Real y = Real.valueOf(LargeInteger.valueOf("-12300"), 
                           LargeInteger.valueOf("5"), -3);
 
      // The real 1.0 with an accuracy of 100 digits. 
     Real one = Real.valueOf(LargeInteger.ONE.E(100), 
                             LargeInteger.ONE, -100);
 

Parameters:

mantissa - this real mantissa.

error - the maximum error on the mantissa.

exponent - the decimal exponent.

Returns:

(mantissa ± error)·10exponent)

Throws:

java.lang.IllegalArgumentException - if error <= 0

valueOf

public static Real valueOf(java.lang.CharSequence chars)
                    throws java.lang.NumberFormatException

Returns the real for the specified character sequence. If the precision is not specified (using the ± symbol), the number of digits is characteristic of the precision. Example of valid character sequences for 1.2 ± 0.001:

• "1.200"
• "1200±1E-3" (no decimal point allowed here)

Parameters:

chars - the character sequence.

Returns:

the corresponding real number.

Throws:

java.lang.NumberFormatException - if the character sequence does not contain a parsable real.

valueOf

public static Real valueOf(double doubleValue)

Converts a double value to a real instance. The error is derived from the inexact representation of double values intrinsic to the 64 bits IEEE 754 format.

Parameters:

doubleValue - the double value to convert.

valueOf

public static Real valueOf(long integer)

Converts an integer value to a real instance. The error is determined by the local integer accuracy setting.

Parameters:

integer - the integer value to convert.

Returns:

a real number corresponding to the specified integer with an an accuracy determined by the local integer accuracy setting.

valueOf

public static Real valueOf(LargeInteger integer)

Converts an integer value to a real instance. The error is determined by the local integer accuracy setting.

Parameters:

integer - the integer value to convert.

Returns:

a real number corresponding to the specified integer with an an accuracy determined by the local integer accuracy setting.

valueOf

public static Real valueOf(XmlElement xml)

XML factory method.

Parameters:

xml - the XML element describing the real to return (e.g. <math:Real value="1.23000"/>).

Returns:

a new Real number as described by the specified xml element.

See Also:

valueOf(CharSequence)

setIntegerAccuracy

public static void setIntegerAccuracy(int accuracy)

Sets the local number of decimal zeros in the fraction part for reals created from integer values (default 18 zeros).

Parameters:

accuracy - the accuracy of reals created from integer values.

See Also:

valueOf(long), valueOf(LargeInteger)

getMantissa

public LargeInteger getMantissa()

Returns this real's mantissa.

Returns:

the mantissa.

getError

public LargeInteger getError()

Returns the maximum error (positive) on this real's mantissa. This methods returns null if this isNaN().

Returns:

the maximum error on the mantissa or null if this.isNaN()

getExponent

public int getExponent()

Returns the exponent of the power of 10 multiplier.

Returns:

the decimal exponent.

getAccuracy

public int getAccuracy()

Returns the number of decimal digits guaranteed exact which appear to the right of the decimal point (absolute error).

Returns:

a measure of the absolute error of this real number.

getPrecision

public final int getPrecision()

Returns the total number of decimal digits guaranteed exact (relative error).

Returns:

a measure of the relative error of this real number.

isPositive

public boolean isPositive()

Indicates if this real is greater than zero.

Returns:

this > 0

isNegative

public boolean isNegative()

Indicates if this real is less than zero.

Returns:

this < 0

isNaN

public boolean isNaN()

Indicates if this real is Not-a-Number (unbounded value interval).

Returns:

true if this number has unbounded value interval; false otherwise.

approxEquals

public boolean approxEquals(Real that)

Indicates if this real is approximately equals to the one specified. This method takes into account possible errors (e.g. numeric errors) to make this determination.

Note: This method returns false if this or that isNaN().

Parameters:

that - the real to compare with.

Returns:

this ≈ that

toLargeInteger

public LargeInteger toLargeInteger()

Converts this real to a LargeInteger instance. Any fractional part of this real is discarded.

Returns:

the integer part of this real.

Throws:

java.lang.ArithmeticException - if this.isNaN()

negate

public Real negate()

Returns the negation of this real number.

Returns:

-this.

add

public Real add(Real that)

Returns the sum of this real number with the one specified.

Parameters:

that - the real to be added.

Returns:

this + that.

subtract

public Real subtract(Real that)

Returns the difference between this real number and the one specified.

Parameters:

that - the real to be subtracted.

Returns:

this - that.

multiply

public Real multiply(Real that)

Returns the product of this real number with the one specified.

Parameters:

that - the real multiplier.

Returns:

this * that.

divide

public Real divide(Real that)

Returns this real number divided by the one specified.

Parameters:

that - the real divisor.

Returns:

this / that.

Throws:

java.lang.ArithmeticException - if that.equals(ZERO)

inverse

public final Real inverse()

Returns the inverse of this real number.

Returns:

1 / this.

abs

public Real abs()

Returns the absolute value of this real number.

Returns:

abs(this).

appendTo

public java.lang.StringBuffer appendTo(java.lang.StringBuffer sb)

Appends the decimal text representation of this real number to the StringBuffer argument. Only digits guaranteed to be exact are written.

Parameters:

sb - the StringBuffer to append.

Returns:

the specified StringBuffer.

toString

public java.lang.String toString()

Returns the decimal text representation of this real number.

Returns:

appendTo(new StringBuffer()).toString()

See Also:

appendTo(java.lang.StringBuffer)

equals

public boolean equals(java.lang.Object that)

Compares this real number against the specified object.

Parameters:

that - the object to compare with.

Returns:

true if the objects are the same; false otherwise.

hashCode

public int hashCode()

Returns the hash code for this real number.

Returns:

the hash code value.

intValue

public int intValue()

Returns the value of this real number as an int.

Returns:

the numeric value represented by this real after conversion to type int.

longValue

public long longValue()

Returns the value of this real number as a long.

Returns:

the numeric value represented by this real after conversion to type long.

floatValue

public float floatValue()

Returns the value of this real number as a float.

Returns:

the numeric value represented by this real after conversion to type float.

doubleValue

public double doubleValue()

Returns the value of this real number as a double.

Returns:

the numeric value represented by this real after conversion to type double.

compareTo

public int compareTo(java.lang.Object that)

Compares two real numbers numerically.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

that - the real to compare with.

Returns:

-1, 0 or 1 as this real is numerically less than, equal to, or greater than that.

Throws:

java.lang.ClassCastException - that is not a Real.

plus

public Operable plus(Operable that)

Description copied from interface: Operable

Returns the sum of this object with the one specified.

Specified by:

plus in interface Operable

Parameters:

that - the object to be added.

Returns:

this + that.

opposite

public Operable opposite()

Description copied from interface: Operable

Returns the additive inverse of this object. It is the object such as this.plus(this.opposite()) == ZERO, with ZERO being the additive identity.

Specified by:

opposite in interface Operable

Returns:

-this.

times

public Operable times(Operable that)

Description copied from interface: Operable

Returns the product of this object with the one specified.

Specified by:

times in interface Operable

Parameters:

that - the object multiplier.

Returns:

this * that.

reciprocal

public Operable reciprocal()

Description copied from interface: Operable

Returns the multiplicative inverse of this object. It it the object such as this.times(this.reciprocal()) == ONE , with ONE being the multiplicative identity.

Specified by:

reciprocal in interface Operable

Returns:

ONE / this.

toXml

public void toXml(XmlElement xml)

Description copied from interface: Representable

Sets the attributes and content of the XML element corresponding to this object.

Specified by:

toXml in interface Representable

Parameters:

xml - the XML element to set according to this object's desired XML representation.

export

public java.lang.Object export()

Description copied from interface: Realtime

Exports this object out of the current pool context. Realtime members are exported as well (recursion). This method affects only objects belonging to the current pool context. To avoid pool depletion, a "free" object from the outer pool is moved to replace the object being exported.

Specified by:

export in interface Realtime

Overrides:

export in class RealtimeNumber

toHeap

public java.lang.Object toHeap()

Description copied from interface: Realtime

Moves this object to the heap. Realtime members are moved to the heap as well (recursion). This method affects only objects belonging to a pool context (current or not).

Specified by:

toHeap in interface Realtime

Overrides:

toHeap in class RealtimeNumber