Package org.apache.sis.internal.util

Class DoubleDouble

java.lang.Object
java.lang.Number
org.apache.sis.internal.util.DoubleDouble
All Implemented Interfaces:
Serializable
public final class DoubleDouble extends Number
Basic arithmetic methods for extended precision numbers using the double-double algorithm. This class implements some of the methods published in the following paper:
  • Yozo Hida, Xiaoye S. Li, David H. Bailey. Library for Double-Double and Quad-Double arithmetic, 2007.
  • Jonathan R. Shewchuk. Adaptive precision floating-point arithmetic and fast robust geometric predicates. Discrete & Computational Geometry, 18(3):305–363, 1997.
DoubleDouble is used as an alternative to BigDecimal when we do not need arbitrary precision, we do not want to convert from base 2 to base 10, we need support for NaN and infinities, we want more compact storage and better performance. DoubleDouble can be converted to BigDecimal as below:

Impact of availability of FMA instructions

When allowed to use fused multiply-add (FMA) instruction added in JDK9 (see SIS-136 on Apache SIS JIRA), then the following methods should be revisited:
Since:
0.4
Version:
1.3
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final boolean
    DISABLED
    true for disabling the extended precision.
    double
    error
    The error that shall be added to the main value in order to get the "real" (actually "the most accurate that we can") value.
    private static final double[]
    ERRORS
    The errors associated to the values in the VALUES array.
    static final double
    MAX_VALUE
    Maximal value that can be handled by multiply(double, double).
    private static final long
    serialVersionUID
    For cross-version compatibility.
    private static final double
    SPLIT
    The split constant used as part of multiplication algorithms.
    double
    value
    The main value, minus the error.
    private static final double[]
    VALUES
    Pre-defined constants frequently used in SIS, sorted in increasing order.
    private static final int
    ZERO_THRESHOLD
    When computing a - b as a double-double (106 significand bits) value, if the amount of non-zero significand bits is equal or lower than ZERO_THRESHOLD+1, consider the result as zero.

  • Constructor Summary

    Constructors
    Constructor
    Description
    DoubleDouble()
    Creates a new value initialized to zero.
    DoubleDouble(double value)
    Creates a new instance initialized to the given value verbatim, without inferring an error term for double-double arithmetic.
    DoubleDouble(double value, double error)
    Creates a new value initialized to the given value and error.
    DoubleDouble(long value)
    Creates a new instance initialized to the given long integer.
    DoubleDouble(Number otherValue)
    Creates a new value initialized to the given number.
    DoubleDouble(DoubleDouble other)
    Creates a new value initialized to the given value.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    add(double otherValue)
    Adds a double value to this DoubleDouble without error term.
    void
    add(double[] array, int index, int errorOffset)
    Adds another double-double value to this DoubleDouble, reading the values from an array.
    void
    add(double otherValue, double otherError)
    Adds another double-double value to this DoubleDouble.
    void
    add(DoubleDouble other)
    Adds another double-double value to this DoubleDouble.
    void
    addGuessError(double otherValue)
    Adds a double value to this DoubleDouble with a default error term.
    void
    addGuessError(Number other)
    Adds a Number value to this DoubleDouble.
    void
    addKahan(double y)
    Adds the given double value using Kahan summation algorithm.
    static DoubleDouble
    castOrCopy(Number value)
    Returns the given value as a DoubleDouble.
    void
    clear()
    Resets the value and error terms to zero.
    static DoubleDouble
    createAndGuessError(double value)
    Creates a new value initialized to the given value and an error term inferred by errorForWellKnownValue(double).
    static DoubleDouble
    createDegreesToRadians()
    Returns a new DoubleDouble instance initialized to the conversion factor from angular degrees to radians.
    static DoubleDouble
    createPi()
    Returns a new DoubleDouble instance initialized to the π value.
    static DoubleDouble
    createRadiansToDegrees()
    Returns a new DoubleDouble instance initialized to the conversion factor from radians to angular degrees.
    static DoubleDouble
    createSecondsToRadians()
    Returns a new DoubleDouble instance initialized to the conversion factor from arc-seconds to radians.
    void
    divide(double otherValue)
    Divides this DoubleDouble by a double without error term.
    void
    divide(double[] array, int index, int errorOffset)
    Divides this DoubleDouble by another double-double value stored in the given array.
    void
    divide(double denominatorValue, double denominatorError)
    Divides this DoubleDouble by another double-double value.
    void
    divide(DoubleDouble other)
    Divides this DoubleDouble by another double-double value.
    void
    divideGuessError(double otherValue)
    Divides this DoubleDouble by a double with a default error term.
    void
    divideGuessError(Number other)
    Divides this DoubleDouble by a Number.
    double
    doubleValue()
     
    boolean
    equals(Object obj)
    Compares this number with the given object for equality.
    static double
    errorForWellKnownValue(double value)
    Suggests an error for the given value.
    float
    floatValue()
     
    int
    hashCode()
    Returns a hash code value for this number.
    int
    intValue()
     
    void
    inverseDivide(double numeratorValue)
    Divides the given double value by this DoubleDouble without error term.
    void
    inverseDivide(double[] array, int index, int errorOffset)
    Divides the given double-double value by this DoubleDouble.
    void
    inverseDivide(double numeratorValue, double numeratorError)
    Divides the given double-double value by this DoubleDouble.
    void
    inverseDivide(DoubleDouble other)
    Divides the given double-double value by this DoubleDouble.
    void
    inverseDivideGuessError(double numeratorValue)
    Divides the given double value by this DoubleDouble with a default error term.
    void
    inverseDivideGuessError(Number other)
    Divides the given Number value by this DoubleDouble.
    boolean
    isZero()
    Returns true if this DoubleDouble is equal to zero.
    long
    longValue()
     
    void
    multiply(double otherValue)
    Multiplies this DoubleDouble by a double without error term.
    void
    multiply(double[] array, int index, int errorOffset)
    Multiplies this DoubleDouble by another double-double value stored in the given array.
    void
    multiply(double otherValue, double otherError)
    Multiplies this DoubleDouble by another double-double value.
    void
    multiply(DoubleDouble other)
    Multiplies this DoubleDouble by another double-double value.
    void
    multiplyGuessError(double otherValue)
    Multiplies this DoubleDouble by a double with a default error term.
    void
    multiplyGuessError(Number other)
    Multiplies this DoubleDouble by a Number.
    void
    negate()
    Sets this number to -this.
    (package private) final void
    normalize()
    Equivalent to a call to setToQuickSum(value, error) inlined.
    void
    ratio_1m_1p()
    Computes (1-x)/(1+x) where x is this.
    void
    series(double... coefficients)
    Computes c₀ + c₁x + c₂x² + c₃x³ + c₄x⁴ + … where x is this.
    void
    set(long n)
    Sets this DoubleDouble to the given 64-bits signed integer.
    void
    setFrom(double[] array, int index, int errorOffset)
    Sets the value and error terms to values read from the given array.
    void
    setFrom(DoubleDouble other)
    Sets this DoubleDouble to the same value than the given instance.
    void
    setToProduct(double a, double b)
    Sets this DoubleDouble to the product of the given numbers.
    (package private) final void
    setToQuickSum(double a, double b)
    Sets this DoubleDouble to the sum of the given numbers, to be used only when abs(a) >= abs(b).
    void
    setToSum(double a, double b)
    Sets this DoubleDouble to the sum of the given numbers.
    static boolean
    shouldConvert(Number value)
    Returns true if the given value is one of the special cases recognized by the DoubleDouble(Number) constructor.
    void
    sqrt()
    Sets this double-double value to its square root.
    void
    square()
    Computes the square of this value.
    void
    storeTo(double[] array, int index, int errorOffset)
    Stores the value and error terms in the given array.
    void
    subtract(double otherValue)
    Subtracts a double from this DoubleDouble without error term.
    void
    subtract(double[] array, int index, int errorOffset)
    Subtracts another double-double value from this DoubleDouble, reading the values from an array.
    void
    subtract(double otherValue, double otherError)
    Subtracts another double-double value from this DoubleDouble.
    void
    subtract(DoubleDouble other)
    Subtracts another double-double value from this DoubleDouble.
    void
    subtractGuessError(double otherValue)
    Subtracts a double from this DoubleDouble with a default error term.
    void
    subtractGuessError(Number other)
    Subtracts a Number from this DoubleDouble.
    static void
    swap(double[] array, int i0, int i1, int errorOffset)
    Swaps two double-double values in the given array.
    String
    toString()
    Returns a string representation of this number for debugging purpose.

    Methods inherited from class java.lang.Number

    byteValue, shortValue

    Methods inherited from class java.lang.Object

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

  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      For cross-version compatibility.
      See Also:

    • DISABLED

      public static final boolean DISABLED
      true for disabling the extended precision. This variable should always be false, except for testing purpose. If set to true, then all double-double arithmetic operations are immediately followed by a clearing of error. The result should then be identical to computation performed using the normal double arithmetic.

      Since this flag is static final, all expressions of the form if (DISABLED) should be omitted by the compiler from the class files in normal operations.

      Setting this flag to true causes some JUnit tests to fail. This is normal. The main purpose of this flag is to allow org.apache.sis.referencing.operation.matrix.MatrixTestCase to perform strict comparisons of matrix operation results with JAMA, which is taken as the reference implementation. Since JAMA uses double arithmetic, SIS needs to disable double-double arithmetic if the results are to be compared for strict equality.

      See Also:

    • ZERO_THRESHOLD

      private static final int ZERO_THRESHOLD
      When computing a - b as a double-double (106 significand bits) value, if the amount of non-zero significand bits is equal or lower than ZERO_THRESHOLD+1, consider the result as zero.
      See Also:

    • SPLIT

      private static final double SPLIT
      The split constant used as part of multiplication algorithms. The split algorithm is as below (we have to inline it in multiplication methods because Java cannot return multi-values):

      Source: [Hida & al.] page 4 algorithm 5, itself reproduced from [Shewchuk] page 325.

      See Also:

    • MAX_VALUE

      public static final double MAX_VALUE
      Maximal value that can be handled by multiply(double, double). If a multiplication is using a value greater than MAX_VALUE, then the result will be infinity or NaN.
      See Also:

    • VALUES

      private static final double[] VALUES
      Pre-defined constants frequently used in SIS, sorted in increasing order. This table contains only constants that cannot be inferred by DecimalFunctions.deltaForDoubleToDecimal(double), for example some transcendental values.

      Elements in this array shall be sorted in strictly increasing order. For any value at index i, the associated error is ERRORS[i].

      See Also:

    • ERRORS

      private static final double[] ERRORS
      The errors associated to the values in the VALUES array.

      Tips:

      • To compute a new value in this array, just put zero and execute DoubleDoubleTest.testErrorForWellKnownValue(). The error message will give the expected value.
      • If a computed value is zero, then there is no point to create an entry in the (VALUES, ERRORS) arrays for that value.

    • value

      public double value
      The main value, minus the error.

    • error

      public double error
      The error that shall be added to the main value in order to get the "real" (actually "the most accurate that we can") value.

  • Constructor Details

    • DoubleDouble

      public DoubleDouble()
      Creates a new value initialized to zero.

    • DoubleDouble

      public DoubleDouble(DoubleDouble other)
      Creates a new value initialized to the given value.
      Parameters:
      other - the other value to copy.

    • DoubleDouble

      public DoubleDouble(Number otherValue)
      Creates a new value initialized to the given number. If the given number is an instance of DoubleDouble, BigDecimal, BigInteger or Fraction, then the error term will be taken in account.
      Parameters:
      otherValue - the initial value.

    • DoubleDouble

      public DoubleDouble(long value)
      Creates a new instance initialized to the given long integer.
      Parameters:
      value - the long integer value to wrap.

    • DoubleDouble

      public DoubleDouble(double value)
      Creates a new instance initialized to the given value verbatim, without inferring an error term for double-double arithmetic. We use this constructor when the value has been computed using transcendental functions (cosine, logarithm, etc.) in which case there is no way we can infer a meaningful error term. It should also be used when the value is known to have an exact representation as a double primitive type.
      Parameters:
      value - the value to wrap in a DoubleDouble instance.
      See Also:

    • DoubleDouble

      public DoubleDouble(double value, double error)
      Creates a new value initialized to the given value and error. It is caller's responsibility to ensure that the (value, error) pair is normalized.
      Parameters:
      value - the initial value.
      error - the initial error.

  • Method Details

    • shouldConvert

      public static boolean shouldConvert(Number value)
      Returns true if the given value is one of the special cases recognized by the DoubleDouble(Number) constructor. Those special cases should rarely occur, so we do not complicate the code with optimized code paths.

      This method does not test if the given value is already an instance of DoubleDouble. That verification should be done by the caller.

      Parameters:
      value - the value to test.
      Returns:
      true if it is worth to convert the given value to a DoubleDouble.
      Since:
      0.8

    • castOrCopy

      public static DoubleDouble castOrCopy(Number value)
      Returns the given value as a DoubleDouble. This method returns the given instance directly if it can be safely casted to DoubleDouble.
      Parameters:
      value - the value to cast or to copy, or null.
      Returns:
      the value as a DoubleDouble (may be the same instance than the given argument), or null if the given value was null.
      Since:
      0.8

    • createAndGuessError

      public static DoubleDouble createAndGuessError(double value)
      Creates a new value initialized to the given value and an error term inferred by errorForWellKnownValue(double). Tip: if the other value is known to be an integer or a power of 2, then invoking DoubleDouble(value) is more efficient.
      Parameters:
      value - the initial value.
      Returns:
      an instance initialized to the given value and a default error term.

    • createPi

      public static DoubleDouble createPi()
      Returns a new DoubleDouble instance initialized to the π value.
      Returns:
      an instance initialized to the 3.14159265358979323846264338327950 value.

    • createRadiansToDegrees

      public static DoubleDouble createRadiansToDegrees()
      Returns a new DoubleDouble instance initialized to the conversion factor from radians to angular degrees.
      Returns:
      an instance initialized to the 57.2957795130823208767981548141052 value.

    • createDegreesToRadians

      public static DoubleDouble createDegreesToRadians()
      Returns a new DoubleDouble instance initialized to the conversion factor from angular degrees to radians.
      Returns:
      an instance initialized to the 0.01745329251994329576923690768488613 value.

    • createSecondsToRadians

      public static DoubleDouble createSecondsToRadians()
      Returns a new DoubleDouble instance initialized to the conversion factor from arc-seconds to radians.
      Returns:
      an instance initialized to the 0.000004848136811095359935899141023579480 value.

    • doubleValue

      public double doubleValue()
      Specified by:
      doubleValue in class Number
      Returns:
      value + error.

    • floatValue

      public float floatValue()
      Specified by:
      floatValue in class Number

    • longValue

      public long longValue()
      Specified by:
      longValue in class Number

    • intValue

      public int intValue()
      Specified by:
      intValue in class Number

    • errorForWellKnownValue

      public static double errorForWellKnownValue(double value)
      Suggests an error for the given value. The DoubleDouble class contains a hard-coded list of some frequently used constants, for example for various factors of π. If the given value matches exactly one of those constants, then its error term is returned. Otherwise this method assumes that the given value is defined in base 10 (e.g. many unit conversion factors) and tries to compute an error term with DecimalFunctions.deltaForDoubleToDecimal(double).

      Rational

      SIS often creates matrices for unit conversions, and most conversion factors are defined precisely in base 10. For example, the conversion from feet to metres is defined by a factor of exactly 0.3048, which cannot be represented precisely as a double. Consequently, if a value of 0.3048 is given, we can assume that the intent was to provide the "feet to metres" conversion factor and complete the double-double instance accordingly.
      Parameters:
      value - the value for which to get this error.
      Returns:
      the error for the given value, or 0 if unknown. In the latter case, the base 2 representation of the given value is assumed to be accurate enough.

    • isZero

      public boolean isZero()
      Returns true if this DoubleDouble is equal to zero.
      Returns:
      true if this DoubleDouble is equal to zero.

    • clear

      public void clear()
      Resets the value and error terms to zero.

    • set

      public void set(long n)
      Sets this DoubleDouble to the given 64-bits signed integer.
      Parameters:
      n - the value to set.

    • setFrom

      public void setFrom(DoubleDouble other)
      Sets this DoubleDouble to the same value than the given instance.
      Parameters:
      other - the instance to copy.

    • setFrom

      public void setFrom(double[] array, int index, int errorOffset)
      Sets the value and error terms to values read from the given array. This is a convenience method for a frequently used operation, implemented as below:
      Parameters:
      array - the array from which to get the value and error.
      index - index of the value in the given array.
      errorOffset - offset to add to index in order to get the index of the error in the given array.

    • normalize

      final void normalize()
      Equivalent to a call to setToQuickSum(value, error) inlined. This is invoked after addition or multiplication operations.

    • setToQuickSum

      final void setToQuickSum(double a, double b)
      Sets this DoubleDouble to the sum of the given numbers, to be used only when abs(a) >= abs(b).

      Source: [Hida & al.] page 4 algorithm 3, itself reproduced from [Shewchuk] page 312.

      Parameters:
      a - the first number to add.
      b - the second number to add, which must be smaller than a.

    • setToSum

      public void setToSum(double a, double b)
      Sets this DoubleDouble to the sum of the given numbers.

      Source: [Hida & al.] page 4 algorithm 4, itself reproduced from [Shewchuk] page 314.

      Parameters:
      a - the first number to add.
      b - the second number to add.

    • setToProduct

      public void setToProduct(double a, double b)
      Sets this DoubleDouble to the product of the given numbers. The given numbers shall not be greater than 1.3393857490036326E300 in magnitude.

      Source: [Hida & al.] page 4 algorithm 6, itself reproduced from [Shewchuk] page 326.

      Parameters:
      a - the first number to multiply.
      b - the second number to multiply.

    • storeTo

      public void storeTo(double[] array, int index, int errorOffset)
      Stores the value and error terms in the given array. This is a convenience method for a frequently used operation, implemented as below:
      Parameters:
      array - the array where to store the value and error.
      index - index of the value in the given array.
      errorOffset - offset to add to index in order to get the index of the error in the given array.

    • swap

      public static void swap(double[] array, int i0, int i1, int errorOffset)
      Swaps two double-double values in the given array.
      Parameters:
      array - the array where to swap the values and errors.
      i0 - index of the first value to swap.
      i1 - index of the second value to swap.
      errorOffset - offset to add to the indices in order to get the error indices in the given array.
      See Also:

    • negate

      public void negate()
      Sets this number to -this.

    • add

      public void add(DoubleDouble other)
      Adds another double-double value to this DoubleDouble. This is a convenience method for:
      Parameters:
      other - the other value to add to this DoubleDouble.

    • addGuessError

      public void addGuessError(Number other)
      Adds a Number value to this DoubleDouble. If the given number is an instance of DoubleDouble or Fraction, then the error term will be taken in account.
      Parameters:
      other - the other value to add to this DoubleDouble.

    • addGuessError

      public void addGuessError(double otherValue)
      Adds a double value to this DoubleDouble with a default error term. This is a convenience method for: Tip: if the other value is known to be an integer or a power of 2, then invoking add(otherValue) is more efficient.
      Parameters:
      otherValue - the other value to add to this DoubleDouble.

    • addKahan

      public void addKahan(double y)
      Adds the given double value using Kahan summation algorithm. This can be used when otherValue is known to be smaller than value.
      Parameters:
      y - the other value to add to this DoubleDouble.

    • add

      public void add(double otherValue)
      Adds a double value to this DoubleDouble without error term. This is a convenience method for:
      Parameters:
      otherValue - the other value to add to this DoubleDouble.

    • add

      public void add(double otherValue, double otherError)
      Adds another double-double value to this DoubleDouble. The result is stored in this instance.

      Implementation

      If a and b are DoubleDouble instances, then:
      (a + b)
      can be computed as:
      (a.value + a.error) + (b.value + b.error)
      = (a.value + b.value) + (a.error + b.error)
      keeping in mind that the result of (a.value + b.value) has itself an error which needs to be added to (a.error + b.error). In Java code:
      Parameters:
      otherValue - the other value to add to this DoubleDouble.
      otherError - the error of the other value to add to this DoubleDouble.

    • add

      public void add(double[] array, int index, int errorOffset)
      Adds another double-double value to this DoubleDouble, reading the values from an array. This is a convenience method for a frequently used operation, implemented as below:
      Parameters:
      array - the array from which to get the value and error.
      index - index of the value in the given array.
      errorOffset - offset to add to index in order to get the index of the error in the given array.

    • subtract

      public void subtract(DoubleDouble other)
      Subtracts another double-double value from this DoubleDouble. This is a convenience method for:
      Parameters:
      other - the other value to subtract from this value.

    • subtractGuessError

      public void subtractGuessError(Number other)
      Subtracts a Number from this DoubleDouble. If the given number is an instance of DoubleDouble or Fraction, then the error term will be taken in account.
      Parameters:
      other - the other value to subtract from this DoubleDouble.

    • subtractGuessError

      public void subtractGuessError(double otherValue)
      Subtracts a double from this DoubleDouble with a default error term. This is a convenience method for: Tip: if the other value is known to be an integer or a power of 2, then invoking subtract(otherValue) is more efficient.
      Parameters:
      otherValue - the other value to subtract from this DoubleDouble.

    • subtract

      public void subtract(double otherValue)
      Subtracts a double from this DoubleDouble without error term. This is a convenience method for:
      Parameters:
      otherValue - the other value to subtract from this DoubleDouble.

    • subtract

      public void subtract(double otherValue, double otherError)
      Subtracts another double-double value from this DoubleDouble. The result is stored in this instance.
      Parameters:
      otherValue - the other value to subtract from this DoubleDouble.
      otherError - the error of the other value to subtract from this DoubleDouble.

    • subtract

      public void subtract(double[] array, int index, int errorOffset)
      Subtracts another double-double value from this DoubleDouble, reading the values from an array. This is a convenience method for a frequently used operation, implemented as below:
      Parameters:
      array - the array from which to get the value and error.
      index - index of the value in the given array.
      errorOffset - offset to add to index in order to get the index of the error in the given array.

    • multiply

      public void multiply(DoubleDouble other)
      Multiplies this DoubleDouble by another double-double value. This is a convenience method for:
      Parameters:
      other - the other value to multiply by this value.

    • multiplyGuessError

      public void multiplyGuessError(Number other)
      Multiplies this DoubleDouble by a Number. If the given number is an instance of DoubleDouble or Fraction, then the error term will be taken in account.
      Parameters:
      other - the other value to multiply by this DoubleDouble.

    • multiplyGuessError

      public void multiplyGuessError(double otherValue)
      Multiplies this DoubleDouble by a double with a default error term. This is a convenience method for: Tip: if the other value is known to be an integer or a power of 2, then invoking multiply(otherValue) is more efficient.
      Parameters:
      otherValue - the other value to multiply by this DoubleDouble.

    • multiply

      public void multiply(double otherValue)
      Multiplies this DoubleDouble by a double without error term. This is a convenience method for:
      Parameters:
      otherValue - the other value to multiply by this DoubleDouble.

    • multiply

      public void multiply(double otherValue, double otherError)
      Multiplies this DoubleDouble by another double-double value. The result is stored in this instance.

      Implementation

      If a and b are DoubleDouble instances, then:
      (a * b)
      can be computed as:
      (a.value + a.error) * (b.value + b.error)
      = (a.value * b.value) + (a.error * b.value) + (a.value * b.error) + (a.error * b.error)
      ≅ (a.value * b.value) + (a.error * b.value) + (a.value * b.error)
      The first term is the main product. All other terms are added to the error, keeping in mind that the main product has itself an error. The last term (the product of errors) is ignored because presumed very small. In Java code:
      Parameters:
      otherValue - the other value by which to multiply this DoubleDouble.
      otherError - the error of the other value by which to multiply this DoubleDouble.

    • multiply

      public void multiply(double[] array, int index, int errorOffset)
      Multiplies this DoubleDouble by another double-double value stored in the given array. This is a convenience method for a frequently used operation, implemented as below:
      Parameters:
      array - the array from which to get the value and error.
      index - index of the value in the given array.
      errorOffset - offset to add to index in order to get the index of the error in the given array.

    • divide

      public void divide(DoubleDouble other)
      Divides this DoubleDouble by another double-double value. This is a convenience method for:
      Parameters:
      other - the other value to by which to divide this value.

    • divideGuessError

      public void divideGuessError(Number other)
      Divides this DoubleDouble by a Number. If the given number is an instance of DoubleDouble or Fraction, then the error term will be taken in account.
      Parameters:
      other - the other value by which to divide this DoubleDouble.

    • divideGuessError

      public void divideGuessError(double otherValue)
      Divides this DoubleDouble by a double with a default error term. This is a convenience method for: Tip: if the other value is known to be an integer or a power of 2, then invoking divide(otherValue) is more efficient.
      Parameters:
      otherValue - the other value by which to divide this DoubleDouble.

    • divide

      public void divide(double otherValue)
      Divides this DoubleDouble by a double without error term. This is a convenience method for:
      Parameters:
      otherValue - the other value by which to divide this DoubleDouble.

    • divide

      public void divide(double denominatorValue, double denominatorError)
      Divides this DoubleDouble by another double-double value. The result is stored in this instance.
      Parameters:
      denominatorValue - the other value by which to divide this DoubleDouble.
      denominatorError - the error of the other value by which to divide this DoubleDouble.

    • divide

      public void divide(double[] array, int index, int errorOffset)
      Divides this DoubleDouble by another double-double value stored in the given array. This is a convenience method for a frequently used operation, implemented as below:
      Parameters:
      array - the array from which to get the value and error.
      index - index of the value in the given array.
      errorOffset - offset to add to index in order to get the index of the error in the given array.

    • inverseDivide

      public void inverseDivide(DoubleDouble other)
      Divides the given double-double value by this DoubleDouble. This is a convenience method for:
      Parameters:
      other - the other value to divide by this value.

    • inverseDivideGuessError

      public void inverseDivideGuessError(Number other)
      Divides the given Number value by this DoubleDouble. If the given number is an instance of DoubleDouble or Fraction, then the error term will be taken in account.
      Parameters:
      other - the other value to divide by this DoubleDouble.

    • inverseDivideGuessError

      public void inverseDivideGuessError(double numeratorValue)
      Divides the given double value by this DoubleDouble with a default error term. This is a convenience method for: Tip: if the other value is known to be an integer or a power of 2, then invoking inverseDivide(otherValue) is more efficient.
      Parameters:
      numeratorValue - the other value to divide by this DoubleDouble.

    • inverseDivide

      public void inverseDivide(double numeratorValue)
      Divides the given double value by this DoubleDouble without error term. This is a convenience method for:
      Parameters:
      numeratorValue - the other value to divide by this DoubleDouble.

    • inverseDivide

      public void inverseDivide(double numeratorValue, double numeratorError)
      Divides the given double-double value by this DoubleDouble. The result is stored in this instance.

      Implementation

      If a and b are DoubleDouble instances, then we estimate:
      (a / b) = (a.value / b.value) + remainder / b
      where:
      remainder = a - b * (a.value / b.value)
      Parameters:
      numeratorValue - the other value to divide by this DoubleDouble.
      numeratorError - the error of the other value to divide by this DoubleDouble.

    • inverseDivide

      public void inverseDivide(double[] array, int index, int errorOffset)
      Divides the given double-double value by this DoubleDouble. This is a convenience method for a frequently used operation, implemented as below:
      Parameters:
      array - the array from which to get the value and error.
      index - index of the value in the given array.
      errorOffset - offset to add to index in order to get the index of the error in the given array.

    • ratio_1m_1p

      public void ratio_1m_1p()
      Computes (1-x)/(1+x) where x is this. This pattern occurs in map projections.

    • square

      public void square()
      Computes the square of this value.

    • sqrt

      public void sqrt()
      Sets this double-double value to its square root.

      Implementation

      This method searches for a (r + ε) value where:
      (r + ε)² = value + error
      If we could compute r = sqrt(value + error) with enough precision, then ε would be 0. But with the double type, we can only estimate r ≈ sqrt(value). However, since that r value should be close to the "true" value, then ε should be small.
      value + error = (r + ε)² = r² + 2rε + ε²
      Neglecting ε² on the assumption that |ε| ≪ |r|:
      value + error ≈ r² + 2rε
      Isolating ε:
      ε ≈ (value + error - r²) / (2r)

    • series

      public void series(double... coefficients)
      Computes c₀ + c₁x + c₂x² + c₃x³ + c₄x⁴ + … where x is this. The given c coefficients are presumed accurate in base 2 (i.e. this method does not try to apply a correction for base 10).
      Parameters:
      coefficients - The c coefficients. The array length must be at least 1.

    • hashCode

      public int hashCode()
      Returns a hash code value for this number.
      Overrides:
      hashCode in class Object
      Returns:
      a hash code value.

    • equals

      public boolean equals(Object obj)
      Compares this number with the given object for equality.
      Overrides:
      equals in class Object
      Parameters:
      obj - the other object to compare with this number.
      Returns:
      true if both object are equal.

    • toString

      public String toString()
      Returns a string representation of this number for debugging purpose. The returned string does not need to contains all digits that this DoubleDouble can handle.
      Overrides:
      toString in class Object
      Returns:
      a string representation of this number.