\n\n\n\nReal\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
\n\n\n\n\n
\n
\n
\n\n\n\n
\n
org.jscience.mathematics.number
\n

Class Real

\n
\n
\n
\n
\n
\n
• \n
\n
All Implemented Interfaces:
\n
Serializable, Comparable<Real>, javolution.lang.Immutable, javolution.lang.Realtime, javolution.lang.ValueType, javolution.xml.XMLSerializable, Field<Real>, GroupAdditive<Real>, GroupMultiplicative<Real>, Ring<Real>, Structure<Real>
\n
\n
\n
\n
`public final class Real\nextends Number<Real>\nimplements Field<Real>`
\n

This class represents a real number of arbitrary precision with \n known/guaranteed uncertainty. A real number consists of a \n `significand`, a maximum `error` \n (on the significand value) and a decimal `exponent`: \n (`(significand \xc2\xb1 error) \xc2\xb7 10exponent`).

\n \n

Reals number can be `exact` (e.g. integer values \n scaled by a power of ten). Exactness is maintained for\n `Ring` operations\n (e.g. addition, multiplication), but typically lost when a \n multiplicative `inverse` is calculated. The minimum \n precision used for exact numbers is set by \n `setExactPrecision(int)` (`context local` setting, default\n `19` digits).

\n \n

The actual `precision` and `accuracy` of any real number is available and guaranteed \n (the true/exact value is always within the precision/accuracy range).

\n \n

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

\n \n

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

\n
\n Wikipedia: Real number, \nSerialized Form
\n
• \n
\n
\n
\n
\n
• \n\n
\n
• \n\n\n

Field Summary

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Fields
Modifier and TypeField and Description
`static Real``NaN`\n
Holds a Not-a-Number instance (infinite error).
\n
`static Real``ONE`\n
Holds the exact ONE instance.
\n
`static Real``ZERO`\n
Holds the exact ZERO instance.
\n
\n
• \n
\n\n
\n
• \n\n\n

Method Summary

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Methods
Modifier and TypeMethod and Description
`Real``abs()`\n
Returns the absolute value of this real number.
\n
`boolean``approximates(Real that)`\n
Indicates if this real approximates the one specified.
\n
`int``compareTo(Real that)`\n
Compares two real numbers numerically.
\n
`Real``copy()`\n
Returns a copy of this number \n `allocated` \n by the calling thread (possibly on the stack).
\n
`Real``divide(long divisor)`\n
Returns this real number divided by the specified `int`\n divisor.
\n
`Real``divide(Real that)`\n
Returns this real number divided by the one specified.
\n
`double``doubleValue()`\n
Returns the value of this real number as a `double`.
\n
`boolean``equals(Object that)`\n
Compares this real number against the specified object.
\n
`int``getAccuracy()`\n
Returns the number of decimal digits guaranteed exact which appear to\n the right of the decimal point (absolute error).
\n
`int``getError()`\n
Returns the maximum error (positive) on this real significand.
\n
`static int``getExactPrecision()`\n
Returns the `local` minimum \n precision (number of exact digits) when exact numbers have to be\n approximated.
\n
`int``getExponent()`\n
Returns the exponent of the power of 10 multiplier.
\n
`int``getPrecision()`\n
Returns the total number of decimal digits guaranteed exact\n (relative error).
\n
`LargeInteger``getSignificand()`\n
Returns this real \n significand value.
\n
`int``hashCode()`\n
Returns the hash code for this real number.
\n
`Real``inverse()`\n
Returns the reciprocal (or inverse) of this real number.
\n
`boolean``isExact()`\n
Indicates if this real number is exact (`error \n == 0`).
\n
`boolean``isLargerThan(Real that)`\n
Compares the absolute value of two real numbers.
\n
`boolean``isNaN()`\n
Indicates if this real is Not-a-Number (unbounded value interval).
\n
`boolean``isNegative()`\n
Indicates if this real is less than zero.
\n
`boolean``isPositive()`\n
Indicates if this real is greater than zero.
\n
`long``longValue()`\n
Returns the value of this real number as a `long`.
\n
`Real``minus(Real that)`\n
Returns the difference between this real number and the one\n specified.
\n
`Real``opposite()`\n
Returns the negation of this real number.
\n
`Real``plus(Real that)`\n
Returns the sum of this real number with the one specified.
\n
`LargeInteger``round()`\n
Returns the closest integer value to this rational number.
\n
`static void``setExactPrecision(int precision)`\n
Sets the `local` minimum precision\n (number of exact digits) when exact numbers have to be approximated.
\n
`Real``sqrt()`\n
Returns the square root of this real number, the more accurate is this \n real number, the more accurate the square root.
\n
`Real``times(long multiplier)`\n
Returns the product of this real number with the specified \n `long` multiplier.
\n
`Real``times(Real that)`\n
Returns the product of this real number with the one specified.
\n
`javolution.text.Text``toText()`\n
Returns the decimal text representation of this number.
\n
`static Real``valueOf(CharSequence chars)`\n
Returns the real for the specified character sequence.
\n
`static Real``valueOf(double doubleValue)`\n
Returns the real number (inexact except for `0.0`) \n corresponding to the specified `double` value.
\n
`static Real``valueOf(LargeInteger significand,\n int error,\n int exponent)`\n
Returns a real having the specified significand, error and exponent values.
\n
`static Real``valueOf(long longValue)`\n
Returns the exact real number corresponding to the specified \n `long` value (convenience method).
\n
\n
\n
• \n\n\n

Methods inherited from class org.jscience.mathematics.number.Number

\n`byteValue, floatValue, intValue, isGreaterThan, isLessThan, pow, shortValue, toString`
• \n
\n
\n
• \n\n\n

Methods inherited from class java.lang.Object

\n`getClass, notify, notifyAll, wait, wait, wait`
• \n
\n
• \n
\n
• \n
\n
\n
\n
\n
• \n\n
\n
• \n\n\n

Field Detail

\n\n\n\n
\n
• \n

NaN

\n
`public static final Real NaN`
\n
Holds a Not-a-Number instance (infinite error).
\n
• \n
\n\n\n\n
\n
• \n

ZERO

\n
`public static final Real ZERO`
\n
Holds the exact ZERO instance.
\n
• \n
\n\n\n\n
\n
• \n

ONE

\n
`public static final Real ONE`
\n
Holds the exact ONE instance.
\n
• \n
\n
• \n
\n\n
\n
• \n\n\n

Method Detail

\n\n\n\n
\n
• \n

getExactPrecision

\n
`public static int getExactPrecision()`
\n
Returns the `local` minimum \n precision (number of exact digits) when exact numbers have to be\n approximated.
\n
Returns:
the minimum number of digits assumed exact for `exact` real numbers.
\n
• \n
\n\n\n\n
\n
• \n

setExactPrecision

\n
`public static void setExactPrecision(int precision)`
\n
Sets the `local` minimum precision\n (number of exact digits) when exact numbers have to be approximated.
\n
Parameters:
`precision` - the minimum number of digits assumed exact for \n `exact` numbers.
\n
• \n
\n\n\n\n
\n
• \n

valueOf

\n
`public static Real valueOf(LargeInteger significand,\n           int error,\n           int exponent)`
\n
Returns a real having the specified significand, error and exponent values.\n If the error is `0`, the real is assumed exact. \n For example:`\n \n // x = 0.0 \xc2\xb1 0.01 \n Real x = Real.valueOf(LargeInteger.ZERO, 1, -2);\n \n // y = -12.3 exact \n Real y = Real.valueOf(LargeInteger.valueOf(-123), 0, -1);\n \n `
\n
Parameters:
`significand` - this real significand.
`error` - the maximum error on the significand.
`exponent` - the decimal exponent.
\n
Returns:
`(significand \xc2\xb1 error)\xc2\xb710exponent)`
\n
Throws:
\n
`IllegalArgumentException` - if `error < 0`
\n
• \n
\n\n\n\n
\n
• \n

valueOf

\n
`public static Real valueOf(double doubleValue)`
\n
Returns the real number (inexact except for `0.0`) \n corresponding to the specified `double` value. \n The error is derived from the inexact representation of \n `double` values intrinsic to the 64 bits IEEE 754 format.
\n
Parameters:
`doubleValue` - the `double` value to convert.
\n
Returns:
the corresponding real number.
\n
• \n
\n\n\n\n
\n
• \n

valueOf

\n
`public static Real valueOf(long longValue)`
\n
Returns the exact real number corresponding to the specified \n `long` value (convenience method).
\n
Parameters:
`longValue` - the exact long value.
\n
Returns:
`Real.valueOf(LargeInteger.valueOf(longValue), 0, 0)`
\n
• \n
\n\n\n\n
\n
• \n

valueOf

\n
`public static Real valueOf(CharSequence chars)\n                    throws NumberFormatException`
\n
Returns the real for the specified character sequence.\n If the precision is not specified (using the `\xc2\xb1` symbol), \n the real is supposed exact. Example of valid character sequences:\n
• "1.2E3" (1200 exact)
• \n
• "1.2E3\xc2\xb11E-2" (1200 \xc2\xb1 0.01)
\n
Parameters:
`chars` - the character sequence.
\n
Returns:
the corresponding real number.
\n
Throws:
\n
`NumberFormatException` - if the character sequence does not contain\n a parsable real.
\n\n\n\n\n\n
\n
• \n

getSignificand

\n
`public LargeInteger getSignificand()`
\n
Returns this real \n significand value.
\n
Returns:
the significand.
\n
• \n
\n\n\n\n
\n
• \n

getError

\n
`public int getError()`
\n
Returns the maximum error (positive) on this real significand.
\n
Returns:
the maximum error on the significand.
\n
• \n
\n\n\n\n
\n
• \n

getExponent

\n
`public int getExponent()`
\n
Returns the exponent of the power of 10 multiplier.
\n
Returns:
the decimal exponent.
\n
• \n
\n\n\n\n
\n
• \n

isExact

\n
`public boolean isExact()`
\n
Indicates if this real number is exact (`error \n == 0`).
\n
Returns:
`getError() == 0`
\n
• \n
\n\n\n\n
\n
• \n

getAccuracy

\n
`public int getAccuracy()`
\n
Returns the number of decimal digits guaranteed exact which appear to\n the right of the decimal point (absolute error).
\n
Returns:
a measure of the absolute error of this real number.
\n
• \n
\n\n\n\n
\n
• \n

getPrecision

\n
`public final int getPrecision()`
\n
Returns the total number of decimal digits guaranteed exact\n (relative error).
\n
Returns:
a measure of the relative error of this real number.
\n
• \n
\n\n\n\n
\n
• \n

isPositive

\n
`public boolean isPositive()`
\n
Indicates if this real is greater than zero.
\n
Returns:
`this > 0`
\n
• \n
\n\n\n\n
\n
• \n

isNegative

\n
`public boolean isNegative()`
\n
Indicates if this real is less than zero.
\n
Returns:
`this < 0`
\n
• \n
\n\n\n\n
\n
• \n

isNaN

\n
`public boolean isNaN()`
\n
Indicates if this real is Not-a-Number (unbounded value interval).
\n
Returns:
`true` if this number has unbounded value interval;\n `false` otherwise.
\n
• \n
\n\n\n\n
\n
• \n

approximates

\n
`public boolean approximates(Real that)`
\n
Indicates if this real approximates the one specified. \n This method takes into account possible errors (e.g. numeric\n errors) to make this determination.\n \n

Note: This method returns `true` if `this` or \n `that` `isNaN()` (basically Not-A-Number \n approximates anything).

\n
Parameters:
`that` - the real to compare with.
\n
Returns:
`this ≈ that`
\n
• \n
\n\n\n\n
\n
• \n

round

\n
`public LargeInteger round()`
\n
Returns the closest integer value to this rational number.
\n
Returns:
this real rounded to the nearest integer.
\n
Throws:
\n
`ArithmeticException` - if `this.isNaN()`
\n
• \n
\n\n\n\n
\n
• \n

opposite

\n
`public Real opposite()`
\n
Returns the negation of this real number.
\n
\n
Specified by:
\n
`opposite` in interface `GroupAdditive<Real>`
\n
Returns:
`-this`.
\n
• \n
\n\n\n\n
\n
• \n

plus

\n
`public Real plus(Real that)`
\n
Returns the sum of this real number with the one specified.
\n
\n
Specified by:
\n
`plus` in interface `GroupAdditive<Real>`
\n
Parameters:
`that` - the real to be added.
\n
Returns:
`this + that`.
\n
• \n
\n\n\n\n
\n
• \n

minus

\n
`public Real minus(Real that)`
\n
Returns the difference between this real number and the one\n specified.
\n
\n
Overrides:
\n
`minus` in class `Number<Real>`
\n
Parameters:
`that` - the real to be subtracted.
\n
Returns:
`this - that`.
\n
• \n
\n\n\n\n
\n
• \n

times

\n
`public Real times(long multiplier)`
\n
Returns the product of this real number with the specified \n `long` multiplier.
\n
Parameters:
`multiplier` - the `long` multiplier.
\n
Returns:
`this \xc2\xb7 multiplier`.
\n
• \n
\n\n\n\n
\n
• \n

times

\n
`public Real times(Real that)`
\n
Returns the product of this real number with the one specified.
\n
\n
Specified by:
\n
`times` in interface `GroupMultiplicative<Real>`
\n
Specified by:
\n
`times` in interface `Ring<Real>`
\n
Parameters:
`that` - the real multiplier.
\n
Returns:
`this \xc2\xb7 that`.
\n
• \n
\n\n\n\n
\n
• \n

divide

\n
`public Real divide(long divisor)`
\n
Returns this real number divided by the specified `int`\n divisor.
\n
Parameters:
`divisor` - the `int` divisor.
\n
Returns:
`this / divisor`
\n
• \n
\n\n\n\n
\n
• \n

divide

\n
`public Real divide(Real that)`
\n
Returns this real number divided by the one specified.
\n
Parameters:
`that` - the real divisor.
\n
Returns:
`this / that`.
\n
Throws:
\n
`ArithmeticException` - if `that.equals(ZERO)`
\n
• \n
\n\n\n\n
\n
• \n

inverse

\n
`public Real inverse()`
\n
Returns the reciprocal (or inverse) of this real number.
\n
\n
Specified by:
\n
`inverse` in interface `GroupMultiplicative<Real>`
\n
Returns:
`1 / this`.
\n
• \n
\n\n\n\n
\n
• \n

abs

\n
`public Real abs()`
\n
Returns the absolute value of this real number.
\n
Returns:
`|this|`.
\n
• \n
\n\n\n\n
\n
• \n

isLargerThan

\n
`public boolean isLargerThan(Real that)`
\n
Compares the absolute value of two real numbers.
\n
\n
Specified by:
\n
`isLargerThan` in class `Number<Real>`
\n
Parameters:
`that` - the real number to be compared with.
\n
Returns:
`|this| > |that|`
\n
• \n
\n\n\n\n
\n
• \n

sqrt

\n
`public Real sqrt()`
\n
Returns the square root of this real number, the more accurate is this \n real number, the more accurate the square root.
\n
Returns:
the positive square root of this real number.
\n
• \n
\n\n\n\n
\n
• \n

toText

\n
`public javolution.text.Text toText()`
\n
Returns the decimal text representation of this number.
\n
\n
Specified by:
\n
`toText` in interface `javolution.lang.Realtime`
\n
Specified by:
\n
`toText` in class `Number<Real>`
\n
Returns:
the text representation of this number.
\n
• \n
\n\n\n\n
\n
• \n

equals

\n
`public boolean equals(Object that)`
\n
Compares this real number against the specified object.\n \n

Note: This method returns `true` if `this` or \n `that` `is Not-A-Number`, even though\n `Double.NaN == Double.NaN` has the value\n `false`.

\n
\n
Specified by:
\n
`equals` in class `Number<Real>`
\n
Parameters:
`that` - the object to compare with.
\n
Returns:
`true` if the objects are two reals with same \n significand, error and exponent;`false` otherwise.
\n
• \n
\n\n\n\n
\n
• \n

hashCode

\n
`public int hashCode()`
\n
Returns the hash code for this real number.
\n
\n
Specified by:
\n
`hashCode` in class `Number<Real>`
\n
Returns:
the hash code value.
\n
• \n
\n\n\n\n
\n
• \n

longValue

\n
`public long longValue()`
\n
Returns the value of this real number as a `long`.
\n
\n
Specified by:
\n
`longValue` in class `Number<Real>`
\n
Returns:
the numeric value represented by this real after conversion\n to type `long`.
\n
• \n
\n\n\n\n
\n
• \n

doubleValue

\n
`public double doubleValue()`
\n
Returns the value of this real number as a `double`.
\n
\n
Specified by:
\n
`doubleValue` in class `Number<Real>`
\n
Returns:
the numeric value represented by this real after conversion\n to type `double`.
\n
• \n
\n\n\n\n
\n
• \n

compareTo

\n
`public int compareTo(Real that)`
\n
Compares two real numbers numerically.
\n
\n
Specified by:
\n
`compareTo` in interface `Comparable<Real>`
\n
Specified by:
\n
`compareTo` in class `Number<Real>`
\n
Parameters:
`that` - the real to compare with.
\n
Returns:
-1, 0 or 1 as this real is numerically less than, equal to,\n or greater than `that`.
\n
Throws:
\n
`ClassCastException` - `that` is not a `Real`.
\n
• \n
\n\n\n\n
\n
• \n

copy

\n
`public Real copy()`
\n
Description copied from class: `Number`
\n
Returns a copy of this number \n `allocated` \n by the calling thread (possibly on the stack).
\n
\n
Specified by:
\n
`copy` in interface `javolution.lang.ValueType`
\n
Specified by:
\n
`copy` in class `Number<Real>`
\n
Returns:
an identical and independant copy of this number.
\n
• \n
\n\n\n\n\n
\n
\n\n\n
\n\n\n\n\n
\n
\n
\n\n\n