Class DD

java.lang.Object
org.locationtech.jts.math.DD
All Implemented Interfaces:
Serializable, Cloneable, Comparable

public final class DD extends Object implements Serializable, Comparable, Cloneable
Implements extended-precision floating-point numbers which maintain 106 bits (approximately 30 decimal digits) of precision.

A DoubleDouble uses a representation containing two double-precision values. A number x is represented as a pair of doubles, x.hi and x.lo, such that the number represented by x is x.hi + x.lo, where

    |x.lo| <= 0.5*ulp(x.hi)
 
and ulp(y) means "unit in the last place of y". The basic arithmetic operations are implemented using convenient properties of IEEE-754 floating-point arithmetic.

The range of values which can be represented is the same as in IEEE-754. The precision of the representable numbers is twice as great as IEEE-754 double precision.

The correctness of the arithmetic algorithms relies on operations being performed with standard IEEE-754 double precision and rounding. This is the Java standard arithmetic model, but for performance reasons Java implementations are not constrained to using this standard by default. Some processors (notably the Intel Pentium architecture) perform floating point operations in (non-IEEE-754-standard) extended-precision. A JVM implementation may choose to use the non-standard extended-precision as its default arithmetic mode. To prevent this from happening, this code uses the Java strictfp modifier, which forces all operations to take place in the standard IEEE-754 rounding model.

The API provides both a set of value-oriented operations and a set of mutating operations. Value-oriented operations treat DoubleDouble values as immutable; operations on them return new objects carrying the result of the operation. This provides a simple and safe semantics for writing DoubleDouble expressions. However, there is a performance penalty for the object allocations required. The mutable interface updates object values in-place. It provides optimum memory performance, but requires care to ensure that aliasing errors are not created and constant values are not changed.

For example, the following code example constructs three DD instances: two to hold the input values and one to hold the result of the addition.

     DD a = new DD(2.0);
     DD b = new DD(3.0);
     DD c = a.add(b);
 
In contrast, the following approach uses only one object:
     DD a = new DD(2.0);
     a.selfAdd(3.0);
 

This implementation uses algorithms originally designed variously by Knuth, Kahan, Dekker, and Linnainmaa. Douglas Priest developed the first C implementation of these techniques. Other more recent C++ implementation are due to Keith M. Briggs and David Bailey et al.

References

  • Priest, D., Algorithms for Arbitrary Precision Floating Point Arithmetic, in P. Kornerup and D. Matula, Eds., Proc. 10th Symposium on Computer Arithmetic, IEEE Computer Society Press, Los Alamitos, Calif., 1991.
  • Yozo Hida, Xiaoye S. Li and David H. Bailey, Quad-Double Arithmetic: Algorithms, Implementation, and Application, manuscript, Oct 2000; Lawrence Berkeley National Laboratory Report BNL-46996.
  • David Bailey, High Precision Software Directory; http://crd.lbl.gov/~dhbailey/mpdist/index.html
See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final DD
    The value nearest to the constant e (the natural logarithm base).
    static final double
    The smallest representable relative difference between two {link @ DoubleDouble} values
    private double
    The high-order component of the double-double precision value.
    private double
    The low-order component of the double-double precision value.
    private static final int
     
    static final DD
    A value representing the result of an operation which does not return a valid number.
    private static final DD
     
    static final DD
    The value nearest to the constant Pi.
    static final DD
    The value nearest to the constant Pi / 2.
    private static final String
     
    private static final String
     
    private static final double
    The value to split a double-precision value on during multiplication
    private static final DD
     
    static final DD
    The value nearest to the constant 2 * Pi.
  • Constructor Summary

    Constructors
    Constructor
    Description
    DD()
    Creates a new DoubleDouble with value 0.0.
    DD(double x)
    Creates a new DoubleDouble with value x.
    DD(double hi, double lo)
    Creates a new DoubleDouble with value (hi, lo).
    DD(String str)
    Creates a new DoubleDouble with value equal to the argument.
    DD(DD dd)
    Creates a new DoubleDouble with value equal to the argument.
  • Method Summary

    Modifier and Type
    Method
    Description
    abs()
    Returns the absolute value of this value.
    final DD
    add(double y)
    Returns a new DoubleDouble whose value is (this + y).
    final DD
    add(DD y)
    Returns a new DoubleDouble whose value is (this + y).
    Returns the smallest (closest to negative infinity) value that is not less than the argument and is equal to a mathematical integer.
    Creates and returns a copy of this value.
    int
    Compares two DoubleDouble objects numerically.
    static DD
    copy(DD dd)
    Creates a new DoubleDouble with the value of the argument.
    private static DD
     
    final DD
    divide(double y)
    Computes a new DoubleDouble whose value is (this / y).
    final DD
    Computes a new DoubleDouble whose value is (this / y).
    double
    Converts this value to the nearest double-precision number.
    Dumps the components of this number to a string.
    boolean
    Tests whether this value is equal to another DoubleDouble value.
    private String
    extractSignificantDigits(boolean insertDecimalPoint, int[] magnitude)
    Extracts the significant digits in the decimal representation of the argument.
    Returns the largest (closest to positive infinity) value that is not greater than the argument and is equal to a mathematical integer.
    boolean
    ge(DD y)
    Tests whether this value is greater than or equals to another DoubleDouble value.
    private String
    Returns the string for this value if it has a known representation.
    boolean
    gt(DD y)
    Tests whether this value is greater than another DoubleDouble value.
    private final void
    init(double x)
     
    private final void
    init(double hi, double lo)
     
    private final void
    init(DD dd)
     
    int
    Converts this value to the nearest integer.
    boolean
    Tests whether this value is NaN.
    boolean
    Tests whether this value is less than 0.
    boolean
    Tests whether this value is greater than 0.
    boolean
    Tests whether this value is equal to 0.
    boolean
    le(DD y)
    Tests whether this value is less than or equal to another DoubleDouble value.
    boolean
    lt(DD y)
    Tests whether this value is less than another DoubleDouble value.
    private static int
    magnitude(double x)
    Determines the decimal magnitude of a number.
    max(DD x)
    Computes the maximum of this and another DD number.
    min(DD x)
    Computes the minimum of this and another DD number.
    final DD
    multiply(double y)
    Returns a new DoubleDouble whose value is (this * y).
    final DD
    Returns a new DoubleDouble whose value is (this * y).
    final DD
    Returns a new DoubleDouble whose value is -this.
    static DD
    Converts a string representation of a real number into a DoubleDouble value.
    pow(int exp)
    Computes the value of this number raised to an integral power.
    final DD
    Returns a DoubleDouble whose value is 1 / this.
    Rounds this value to the nearest integer.
    final DD
    selfAdd(double y)
    Adds the argument to the value of this.
    private final DD
    selfAdd(double yhi, double ylo)
     
    final DD
    Adds the argument to the value of this.
    final DD
    selfDivide(double y)
    Divides this object by the argument, returning this.
    private final DD
    selfDivide(double yhi, double ylo)
     
    final DD
    Divides this object by the argument, returning this.
    final DD
    selfMultiply(double y)
    Multiplies this object by the argument, returning this.
    private final DD
    selfMultiply(double yhi, double ylo)
     
    final DD
    Multiplies this object by the argument, returning this.
    Squares this object.
    final DD
    selfSubtract(double y)
    Subtracts the argument from the value of this.
    final DD
    Subtracts the argument from the value of this.
    setValue(double value)
    Set the value for the DD object.
    setValue(DD value)
    Set the value for the DD object.
    int
    Returns an integer indicating the sign of this value.
    sqr()
    Computes the square of this value.
    static DD
    sqr(double x)
    Computes the square of this value.
    Computes the positive square root of this value.
    static DD
    sqrt(double x)
     
    private static String
    stringOfChar(char ch, int len)
    Creates a string of a given length containing the given character
    final DD
    subtract(double y)
    Computes a new DoubleDouble object whose value is (this - y).
    final DD
    Computes a new DoubleDouble object whose value is (this - y).
    Returns the string representation of this value in scientific notation.
    Returns the string representation of this value in standard notation.
    Returns a string representation of this number, in either standard or scientific notation.
    Returns the integer which is largest in absolute value and not further from zero than this value.
    static DD
    valueOf(double x)
    Converts the double argument to a DoubleDouble number.
    static DD
    Converts the string argument to a DoubleDouble number.

    Methods inherited from class java.lang.Object

    equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
  • Field Details

    • PI

      public static final DD PI
      The value nearest to the constant Pi.
    • TWO_PI

      public static final DD TWO_PI
      The value nearest to the constant 2 * Pi.
    • PI_2

      public static final DD PI_2
      The value nearest to the constant Pi / 2.
    • E

      public static final DD E
      The value nearest to the constant e (the natural logarithm base).
    • NaN

      public static final DD NaN
      A value representing the result of an operation which does not return a valid number.
    • EPS

      public static final double EPS
      The smallest representable relative difference between two {link @ DoubleDouble} values
      See Also:
    • SPLIT

      private static final double SPLIT
      The value to split a double-precision value on during multiplication
      See Also:
    • hi

      private double hi
      The high-order component of the double-double precision value.
    • lo

      private double lo
      The low-order component of the double-double precision value.
    • MAX_PRINT_DIGITS

      private static final int MAX_PRINT_DIGITS
      See Also:
    • TEN

      private static final DD TEN
    • ONE

      private static final DD ONE
    • SCI_NOT_EXPONENT_CHAR

      private static final String SCI_NOT_EXPONENT_CHAR
      See Also:
    • SCI_NOT_ZERO

      private static final String SCI_NOT_ZERO
      See Also:
  • Constructor Details

    • DD

      public DD()
      Creates a new DoubleDouble with value 0.0.
    • DD

      public DD(double x)
      Creates a new DoubleDouble with value x.
      Parameters:
      x - the value to initialize
    • DD

      public DD(double hi, double lo)
      Creates a new DoubleDouble with value (hi, lo).
      Parameters:
      hi - the high-order component
      lo - the high-order component
    • DD

      public DD(DD dd)
      Creates a new DoubleDouble with value equal to the argument.
      Parameters:
      dd - the value to initialize
    • DD

      public DD(String str) throws NumberFormatException
      Creates a new DoubleDouble with value equal to the argument.
      Parameters:
      str - the value to initialize by
      Throws:
      NumberFormatException - if str is not a valid representation of a number
  • Method Details

    • createNaN

      private static DD createNaN()
    • valueOf

      public static DD valueOf(String str) throws NumberFormatException
      Converts the string argument to a DoubleDouble number.
      Parameters:
      str - a string containing a representation of a numeric value
      Returns:
      the extended precision version of the value
      Throws:
      NumberFormatException - if s is not a valid representation of a number
    • valueOf

      public static DD valueOf(double x)
      Converts the double argument to a DoubleDouble number.
      Parameters:
      x - a numeric value
      Returns:
      the extended precision version of the value
    • copy

      public static DD copy(DD dd)
      Creates a new DoubleDouble with the value of the argument.
      Parameters:
      dd - the DoubleDouble value to copy
      Returns:
      a copy of the input value
    • clone

      public Object clone()
      Creates and returns a copy of this value.
      Overrides:
      clone in class Object
      Returns:
      a copy of this value
    • init

      private final void init(double x)
    • init

      private final void init(double hi, double lo)
    • init

      private final void init(DD dd)
    • setValue

      public DD setValue(DD value)
      Set the value for the DD object. This method supports the mutating operations concept described in the class documentation (see above).
      Parameters:
      value - a DD instance supplying an extended-precision value.
      Returns:
      a self-reference to the DD instance.
    • setValue

      public DD setValue(double value)
      Set the value for the DD object. This method supports the mutating operations concept described in the class documentation (see above).
      Parameters:
      value - a floating point value to be stored in the instance.
      Returns:
      a self-reference to the DD instance.
    • add

      public final DD add(DD y)
      Returns a new DoubleDouble whose value is (this + y).
      Parameters:
      y - the addend
      Returns:
      (this + y)
    • add

      public final DD add(double y)
      Returns a new DoubleDouble whose value is (this + y).
      Parameters:
      y - the addend
      Returns:
      (this + y)
    • selfAdd

      public final DD selfAdd(DD y)
      Adds the argument to the value of this. To prevent altering constants, this method must only be used on values known to be newly created.
      Parameters:
      y - the addend
      Returns:
      this object, increased by y
    • selfAdd

      public final DD selfAdd(double y)
      Adds the argument to the value of this. To prevent altering constants, this method must only be used on values known to be newly created.
      Parameters:
      y - the addend
      Returns:
      this object, increased by y
    • selfAdd

      private final DD selfAdd(double yhi, double ylo)
    • subtract

      public final DD subtract(DD y)
      Computes a new DoubleDouble object whose value is (this - y).
      Parameters:
      y - the subtrahend
      Returns:
      (this - y)
    • subtract

      public final DD subtract(double y)
      Computes a new DoubleDouble object whose value is (this - y).
      Parameters:
      y - the subtrahend
      Returns:
      (this - y)
    • selfSubtract

      public final DD selfSubtract(DD y)
      Subtracts the argument from the value of this. To prevent altering constants, this method must only be used on values known to be newly created.
      Parameters:
      y - the addend
      Returns:
      this object, decreased by y
    • selfSubtract

      public final DD selfSubtract(double y)
      Subtracts the argument from the value of this. To prevent altering constants, this method must only be used on values known to be newly created.
      Parameters:
      y - the addend
      Returns:
      this object, decreased by y
    • negate

      public final DD negate()
      Returns a new DoubleDouble whose value is -this.
      Returns:
      -this
    • multiply

      public final DD multiply(DD y)
      Returns a new DoubleDouble whose value is (this * y).
      Parameters:
      y - the multiplicand
      Returns:
      (this * y)
    • multiply

      public final DD multiply(double y)
      Returns a new DoubleDouble whose value is (this * y).
      Parameters:
      y - the multiplicand
      Returns:
      (this * y)
    • selfMultiply

      public final DD selfMultiply(DD y)
      Multiplies this object by the argument, returning this. To prevent altering constants, this method must only be used on values known to be newly created.
      Parameters:
      y - the value to multiply by
      Returns:
      this object, multiplied by y
    • selfMultiply

      public final DD selfMultiply(double y)
      Multiplies this object by the argument, returning this. To prevent altering constants, this method must only be used on values known to be newly created.
      Parameters:
      y - the value to multiply by
      Returns:
      this object, multiplied by y
    • selfMultiply

      private final DD selfMultiply(double yhi, double ylo)
    • divide

      public final DD divide(DD y)
      Computes a new DoubleDouble whose value is (this / y).
      Parameters:
      y - the divisor
      Returns:
      a new object with the value (this / y)
    • divide

      public final DD divide(double y)
      Computes a new DoubleDouble whose value is (this / y).
      Parameters:
      y - the divisor
      Returns:
      a new object with the value (this / y)
    • selfDivide

      public final DD selfDivide(DD y)
      Divides this object by the argument, returning this. To prevent altering constants, this method must only be used on values known to be newly created.
      Parameters:
      y - the value to divide by
      Returns:
      this object, divided by y
    • selfDivide

      public final DD selfDivide(double y)
      Divides this object by the argument, returning this. To prevent altering constants, this method must only be used on values known to be newly created.
      Parameters:
      y - the value to divide by
      Returns:
      this object, divided by y
    • selfDivide

      private final DD selfDivide(double yhi, double ylo)
    • reciprocal

      public final DD reciprocal()
      Returns a DoubleDouble whose value is 1 / this.
      Returns:
      the reciprocal of this value
    • floor

      public DD floor()
      Returns the largest (closest to positive infinity) value that is not greater than the argument and is equal to a mathematical integer. Special cases:
      • If this value is NaN, returns NaN.
      Returns:
      the largest (closest to positive infinity) value that is not greater than the argument and is equal to a mathematical integer.
    • ceil

      public DD ceil()
      Returns the smallest (closest to negative infinity) value that is not less than the argument and is equal to a mathematical integer. Special cases:
      • If this value is NaN, returns NaN.
      Returns:
      the smallest (closest to negative infinity) value that is not less than the argument and is equal to a mathematical integer.
    • signum

      public int signum()
      Returns an integer indicating the sign of this value.
      • if this value is > 0, returns 1
      • if this value is < 0, returns -1
      • if this value is = 0, returns 0
      • if this value is NaN, returns 0
      Returns:
      an integer indicating the sign of this value
    • rint

      public DD rint()
      Rounds this value to the nearest integer. The value is rounded to an integer by adding 1/2 and taking the floor of the result. Special cases:
      • If this value is NaN, returns NaN.
      Returns:
      this value rounded to the nearest integer
    • trunc

      public DD trunc()
      Returns the integer which is largest in absolute value and not further from zero than this value. Special cases:
      • If this value is NaN, returns NaN.
      Returns:
      the integer which is largest in absolute value and not further from zero than this value
    • abs

      public DD abs()
      Returns the absolute value of this value. Special cases:
      • If this value is NaN, it is returned.
      Returns:
      the absolute value of this value
    • sqr

      public DD sqr()
      Computes the square of this value.
      Returns:
      the square of this value.
    • selfSqr

      public DD selfSqr()
      Squares this object. To prevent altering constants, this method must only be used on values known to be newly created.
      Returns:
      the square of this value.
    • sqr

      public static DD sqr(double x)
      Computes the square of this value.
      Returns:
      the square of this value.
    • sqrt

      public DD sqrt()
      Computes the positive square root of this value. If the number is NaN or negative, NaN is returned.
      Returns:
      the positive square root of this number. If the argument is NaN or less than zero, the result is NaN.
    • sqrt

      public static DD sqrt(double x)
    • pow

      public DD pow(int exp)
      Computes the value of this number raised to an integral power. Follows semantics of Java Math.pow as closely as possible.
      Parameters:
      exp - the integer exponent
      Returns:
      x raised to the integral power exp
    • min

      public DD min(DD x)
      Computes the minimum of this and another DD number.
      Parameters:
      x - a DD number
      Returns:
      the minimum of the two numbers
    • max

      public DD max(DD x)
      Computes the maximum of this and another DD number.
      Parameters:
      x - a DD number
      Returns:
      the maximum of the two numbers
    • doubleValue

      public double doubleValue()
      Converts this value to the nearest double-precision number.
      Returns:
      the nearest double-precision number to this value
    • intValue

      public int intValue()
      Converts this value to the nearest integer.
      Returns:
      the nearest integer to this value
    • isZero

      public boolean isZero()
      Tests whether this value is equal to 0.
      Returns:
      true if this value is equal to 0
    • isNegative

      public boolean isNegative()
      Tests whether this value is less than 0.
      Returns:
      true if this value is less than 0
    • isPositive

      public boolean isPositive()
      Tests whether this value is greater than 0.
      Returns:
      true if this value is greater than 0
    • isNaN

      public boolean isNaN()
      Tests whether this value is NaN.
      Returns:
      true if this value is NaN
    • equals

      public boolean equals(DD y)
      Tests whether this value is equal to another DoubleDouble value.
      Parameters:
      y - a DoubleDouble value
      Returns:
      true if this value = y
    • gt

      public boolean gt(DD y)
      Tests whether this value is greater than another DoubleDouble value.
      Parameters:
      y - a DoubleDouble value
      Returns:
      true if this value > y
    • ge

      public boolean ge(DD y)
      Tests whether this value is greater than or equals to another DoubleDouble value.
      Parameters:
      y - a DoubleDouble value
      Returns:
      true if this value >= y
    • lt

      public boolean lt(DD y)
      Tests whether this value is less than another DoubleDouble value.
      Parameters:
      y - a DoubleDouble value
      Returns:
      true if this value < y
    • le

      public boolean le(DD y)
      Tests whether this value is less than or equal to another DoubleDouble value.
      Parameters:
      y - a DoubleDouble value
      Returns:
      true if this value <= y
    • compareTo

      public int compareTo(Object o)
      Compares two DoubleDouble objects numerically.
      Specified by:
      compareTo in interface Comparable
      Returns:
      -1,0 or 1 depending on whether this value is less than, equal to or greater than the value of o
    • dump

      public String dump()
      Dumps the components of this number to a string.
      Returns:
      a string showing the components of the number
    • toString

      public String toString()
      Returns a string representation of this number, in either standard or scientific notation. If the magnitude of the number is in the range [ 10-3, 108 ] standard notation will be used. Otherwise, scientific notation will be used.
      Overrides:
      toString in class Object
      Returns:
      a string representation of this number
    • toStandardNotation

      public String toStandardNotation()
      Returns the string representation of this value in standard notation.
      Returns:
      the string representation in standard notation
    • toSciNotation

      public String toSciNotation()
      Returns the string representation of this value in scientific notation.
      Returns:
      the string representation in scientific notation
    • extractSignificantDigits

      private String extractSignificantDigits(boolean insertDecimalPoint, int[] magnitude)
      Extracts the significant digits in the decimal representation of the argument. A decimal point may be optionally inserted in the string of digits (as long as its position lies within the extracted digits - if not, the caller must prepend or append the appropriate zeroes and decimal point).
      Parameters:
      y - the number to extract ( >= 0)
      decimalPointPos - the position in which to insert a decimal point
      Returns:
      the string containing the significant digits and possibly a decimal point
    • stringOfChar

      private static String stringOfChar(char ch, int len)
      Creates a string of a given length containing the given character
      Parameters:
      ch - the character to be repeated
      len - the len of the desired string
      Returns:
      the string
    • getSpecialNumberString

      private String getSpecialNumberString()
      Returns the string for this value if it has a known representation. (E.g. NaN or 0.0)
      Returns:
      the string for this special number or null if the number is not a special number
    • magnitude

      private static int magnitude(double x)
      Determines the decimal magnitude of a number. The magnitude is the exponent of the greatest power of 10 which is less than or equal to the number.
      Parameters:
      x - the number to find the magnitude of
      Returns:
      the decimal magnitude of x
    • parse

      public static DD parse(String str) throws NumberFormatException
      Converts a string representation of a real number into a DoubleDouble value. The format accepted is similar to the standard Java real number syntax. It is defined by the following regular expression:
       [+|-] {digit} [ . {digit} ] [ ( e | E ) [+|-] {digit}+
       
      Parameters:
      str - the string to parse
      Returns:
      the value of the parsed number
      Throws:
      NumberFormatException - if str is not a valid representation of a number