Real
org.jscience.mathematics.number

Class Real

  • All Implemented Interfaces:
    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>


    public final class Realextends Number<Real>implements Field<Real>

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

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

    The actual precision and 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.

    See Also:
    Wikipedia: Real number, Serialized Form
    • Field Summary

      Fields 
      Modifier and TypeField and Description
      static RealNaN
      Holds a Not-a-Number instance (infinite error).
      static RealONE
      Holds the exact ONE instance.
      static RealZERO
      Holds the exact ZERO instance.
    • Method Summary

      Methods 
      Modifier and TypeMethod and Description
      Realabs()
      Returns the absolute value of this real number.
      booleanapproximates(Real that)
      Indicates if this real approximates the one specified.
      intcompareTo(Real that)
      Compares two real numbers numerically.
      Realcopy()
      Returns a copy of this number allocated by the calling thread (possibly on the stack).
      Realdivide(long divisor)
      Returns this real number divided by the specified int divisor.
      Realdivide(Real that)
      Returns this real number divided by the one specified.
      doubledoubleValue()
      Returns the value of this real number as a double.
      booleanequals(Object that)
      Compares this real number against the specified object.
      intgetAccuracy()
      Returns the number of decimal digits guaranteed exact which appear to the right of the decimal point (absolute error).
      intgetError()
      Returns the maximum error (positive) on this real significand.
      static intgetExactPrecision()
      Returns the local minimum precision (number of exact digits) when exact numbers have to be approximated.
      intgetExponent()
      Returns the exponent of the power of 10 multiplier.
      intgetPrecision()
      Returns the total number of decimal digits guaranteed exact (relative error).
      LargeIntegergetSignificand()
      Returns this real significand value.
      inthashCode()
      Returns the hash code for this real number.
      Realinverse()
      Returns the reciprocal (or inverse) of this real number.
      booleanisExact()
      Indicates if this real number is exact (error == 0).
      booleanisLargerThan(Real that)
      Compares the absolute value of two real numbers.
      booleanisNaN()
      Indicates if this real is Not-a-Number (unbounded value interval).
      booleanisNegative()
      Indicates if this real is less than zero.
      booleanisPositive()
      Indicates if this real is greater than zero.
      longlongValue()
      Returns the value of this real number as a long.
      Realminus(Real that)
      Returns the difference between this real number and the one specified.
      Realopposite()
      Returns the negation of this real number.
      Realplus(Real that)
      Returns the sum of this real number with the one specified.
      LargeIntegerround()
      Returns the closest integer value to this rational number.
      static voidsetExactPrecision(int precision)
      Sets the local minimum precision (number of exact digits) when exact numbers have to be approximated.
      Realsqrt()
      Returns the square root of this real number, the more accurate is this real number, the more accurate the square root.
      Realtimes(long multiplier)
      Returns the product of this real number with the specified long multiplier.
      Realtimes(Real that)
      Returns the product of this real number with the one specified.
      javolution.text.TexttoText()
      Returns the decimal text representation of this number.
      static RealvalueOf(CharSequence chars)
      Returns the real for the specified character sequence.
      static RealvalueOf(double doubleValue)
      Returns the real number (inexact except for 0.0) corresponding to the specified double value.
      static RealvalueOf(LargeInteger significand, int error, int exponent)
      Returns a real having the specified significand, error and exponent values.
      static RealvalueOf(long longValue)
      Returns the exact real number corresponding to the specified long value (convenience method).
    • Field Detail

      • NaN

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

        public static final Real ZERO
        Holds the exact ZERO instance.
      • ONE

        public static final Real ONE
        Holds the exact ONE instance.
    • Method Detail

      • getExactPrecision

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

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

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

        public static Real valueOf(double doubleValue)
        Returns the real number (inexact except for 0.0) corresponding to the specified double value. 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.
        Returns:
        the corresponding real number.
      • valueOf

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

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

SCaVis 2.2 © jWork.ORG