Class DD
- java.lang.Object
-
- java.lang.Number
-
- org.apache.commons.numbers.core.DD
-
- All Implemented Interfaces:
Serializable,Addition<DD>,Multiplication<DD>,NativeOperators<DD>
public final class DD extends Number implements NativeOperators<DD>, Serializable
Computes double-double floating-point operations.A double-double is an unevaluated sum of two IEEE double precision numbers capable of representing at least 106 bits of significand. A normalized double-double number
(x, xx)satisfies the condition that the parts are non-overlapping in magnitude such that:|x| > |xx| x == x + xx
This implementation assumes a normalized representation during operations on a
DDnumber and computes results as a normalized representation. Any double-double number can be normalized by summation of the parts (seeofSum). Note that the number(x, xx)may also be referred to using the labels high and low to indicate the magnitude of the parts as(xhi, xlo), or using a numerical suffix for the parts as(x0, x1). The numerical suffix is typically used when the number has an arbitrary number of parts.The double-double class is immutable.
Construction
Factory methods to create a
DDthat are exact use the prefixof. Methods that create the closest possible representation use the prefixfrom. These methods may suffer a possible loss of precision during conversion.Primitive values of type
double,intandlongare converted exactly to aDD.The
DDclass can also be created as the result of an arithmetic operation on a pair ofdoubleoperands. The resultingDDhas the IEEE754doubleresult of the operation in the first part, and the second part contains the round-off lost from the operation due to rounding. Construction using add (+), subtract (-) and multiply (*) operators are exact. Construction using division (/) may be inexact if the quotient is not representable.Note that it is more efficient to create a
DDfrom adoubleoperation than to create twoDDvalues and combine them with the same operation. The result will be the same for add, subtract and multiply but may lose precision for divide.// Inefficient DD a = DD.of(1.23).add(DD.of(4.56)); // Optimal DD b = DD.ofSum(1.23, 4.56); // Inefficient and may lose precision DD c = DD.of(1.23).divide(DD.of(4.56)); // Optimal DD d = DD.fromQuotient(1.23, 4.56);It is not possible to directly specify the two parts of the number. The two parts must be added using
ofSum. If the two parts already represent a number(x, xx)such thatx == x + xxthen the magnitudes of the parts will be unchanged; any signed zeros may be subject to a sign change.Primitive operands
Operations are provided using a
DDoperand or adoubleoperand. Implicit type conversion allows methods with adoubleoperand to be used with other primitives such asintorlong. Note that casting of alongto adoublemay result in loss of precision. To maintain the full precision of alongfirst convert the value to aDDusingof(long)and use the same arithmetic operation using theDDoperand.Accuracy
Add and multiply operations using two
doublevalues operands are computed to an exactDDresult (seeofSumandofProduct). Operations involving aDDand another operand, eitherdoubleorDD, are not exact.This class is not intended to perform exact arithmetic. Arbitrary precision arithmetic is available using
BigDecimal. Single operations will compute theDDresult within a tolerance of the 106-bit exact result. This far exceeds the accuracy ofdoublearithmetic. The reduced accuracy is a compromise to deliver increased performance. The class is intended to reduce error in equivalentdoublearithmetic operations where thedoublevalued result is required to high accuracy. Although it is possible to reduce error to 2-106 for all operations, the additional computation would impact performance and would require multiple chained operations to potentially observe a different result when the finalDDis converted to adouble.Canonical representation
The double-double number is the sum of its parts. The canonical representation of the number is the explicit value of the parts. The
toString()method is provided to convert to a String representation of the parts formatted as a tuple.The class implements
equals(Object)andhashCode()and allows usage as a key in a Set or Map. Equality requires binary equivalence of the parts. Note that representations of zero using different combinations of +/- 0.0 are not considered equal. Also note that many non-normalized double-double numbers can represent the same number. Double-double numbers can be normalized before operations that involveequals(Object)byaddingthe parts; this is exact for a finite sum and provides equality support for non-zero numbers. Alternatively exact numerical equality and comparisons are supported by conversion to aBigDecimalrepresentation. Note thatBigDecimaldoes not support non-finite values.Overflow, underflow and non-finite support
A double-double number is limited to the same finite range as a
double(4.9E-324 to 1.7976931348623157E308). This class is intended for use when the ultimate result is finite and intermediate values do not approach infinity or zero.This implementation does not support IEEE standards for handling infinite and NaN when used in arithmetic operations. Computations may split a 64-bit double into two parts and/or use subtraction of intermediate terms to compute round-off parts. These operations may generate infinite values due to overflow which then propagate through further operations to NaN, for example computing the round-off using
Inf - Inf = NaN.Operations that involve splitting a double (multiply, divide) are safe when the base 2 exponent is below 996. This puts an upper limit of approximately +/-6.7e299 on any values to be split; in practice the arguments to multiply and divide operations are further constrained by the expected finite value of the product or quotient.
Likewise the smallest value that can be represented is
Double.MIN_VALUE. The full 106-bit accuracy will be lost when intermediates are within 253 ofDouble.MIN_NORMAL.The
DDresult can be verified by checking it is afiniteevaluated sum. Computations expecting to approach over or underflow must use scaling of intermediate terms (seefrexpandscalb) and appropriate management of the current base 2 scale.References:
- Dekker, T.J. (1971) A floating-point technique for extending the available precision Numerische Mathematik, 18:224–242.
- Shewchuk, J.R. (1997) Arbitrary Precision Floating-Point Arithmetic.
- Hide, Y, Li, X.S. and Bailey, D.H. (2008) Library for Double-Double and Quad-Double Arithmetic.
- Since:
- 1.2
- See Also:
- Serialized Form
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description DDabs()Returns aDDwhose value is the absolute value of the number(x, xx)This method assumes that the low partxxis the smaller magnitude.DDadd(double y)Returns aDDwhose value is(this + y).DDadd(DD y)Returns aDDwhose value is(this + y).BigDecimalbigDecimalValue()Get the value as aBigDecimal.DDceil()Returns the smallest (closest to negative infinity)DDvalue that is greater than or equal tothisnumber(x, xx)and is equal to a mathematical integer.DDdivide(double y)Returns aDDwhose value is(this / y).DDdivide(DD y)Returns aDDwhose value is(this / y).doubledoubleValue()Get the value as adouble.booleanequals(Object other)Test for equality with another object.floatfloatValue()Get the value as afloat.DDfloor()Returns the largest (closest to positive infinity)DDvalue that is less than or equal tothisnumber(x, xx)and is equal to a mathematical integer.DDfrexp(int[] exp)Convertthisnumberxto fractionalfand integral2^expcomponents.static DDfrom(BigDecimal x)Creates the double-double number(z, zz)using thedoublerepresentation of the argumentx; the low part is thedoublerepresentation of the round-off error.static DDfromQuotient(double x, double y)Returns aDDwhose value is(x / y).inthashCode()Gets a hash code for the double-double number.doublehi()Gets the first partxof the double-double number(x, xx).intintValue()Get the value as anint.booleanisFinite()Returnstrueif the evaluated sum of the parts is finite.booleanisOne()Check if this is a neutral element of multiplication, i.e.booleanisZero()Check if this is a neutral element of addition, i.e.doublelo()Gets the second partxxof the double-double number(x, xx).longlongValue()Get the value as along.DDmultiply(double y)Returns aDDwhose value isthis * y.DDmultiply(int n)Repeated addition.DDmultiply(DD y)Returns aDDwhose value isthis * y.DDnegate()Returns aDDwhose value is the negation of both parts of double-double number.static DDof(double x)Creates the double-double number as the value(x, 0).static DDof(int x)Creates the double-double number as the value(x, 0).static DDof(long x)Creates the double-double number with the high part equal to(double) xand the low part equal to any remaining bits.static DDofDifference(double x, double y)Returns aDDwhose value is(x - y).static DDofProduct(double x, double y)Returns aDDwhose value is(x * y).static DDofSquare(double x)Returns aDDwhose value is(x * x).static DDofSum(double x, double y)Returns aDDwhose value is(x + y).DDone()Identity element.DDpow(int n)Computethisnumber(x, xx)raised to the powern.DDpow(int n, long[] exp)Computethisnumberxraised to the powern.DDreciprocal()Compute the reciprocal ofthis.DDscalb(int exp)Multiplythisnumber(x, xx)by an integral power of two.DDsqrt()Compute the square root ofthisnumber(x, xx).DDsquare()Returns aDDwhose value isthis * this.DDsubtract(double y)Returns aDDwhose value is(this - y).DDsubtract(DD y)Returns aDDwhose value is(this - y).StringtoString()Returns a string representation of the double-double number.DDzero()Identity element.-
Methods inherited from class java.lang.Number
byteValue, shortValue
-
-
-
-
Method Detail
-
of
public static DD of(double x)
Creates the double-double number as the value(x, 0).- Parameters:
x- Value.- Returns:
- the double-double
-
of
public static DD of(int x)
Creates the double-double number as the value(x, 0).Note this method exists to avoid using
of(long)forintegerarguments; thelongvariation is slower as it preserves all 64-bits of information.- Parameters:
x- Value.- Returns:
- the double-double
- See Also:
of(long)
-
of
public static DD of(long x)
Creates the double-double number with the high part equal to(double) xand the low part equal to any remaining bits.Note this method preserves all 64-bits of precision. Faster construction can be achieved using up to 53-bits of precision using
of((double) x).- Parameters:
x- Value.- Returns:
- the double-double
- See Also:
of(double)
-
from
public static DD from(BigDecimal x)
Creates the double-double number(z, zz)using thedoublerepresentation of the argumentx; the low part is thedoublerepresentation of the round-off error.double z = x.doubleValue(); double zz = x.subtract(new BigDecimal(z)).doubleValue();
If the value cannot be represented as a finite value the result will have an infinite high part and the low part is undefined.
Note: This conversion can lose information about the precision of the BigDecimal value. The result is the closest double-double representation to the value.
- Parameters:
x- Value.- Returns:
- the double-double
-
ofSum
public static DD ofSum(double x, double y)
Returns aDDwhose value is(x + y). The values are not required to be ordered by magnitude, i.e. the result is commutative:x + y == y + x.This method ignores special handling of non-normal numbers and overflow within the extended precision computation. This creates the following special cases:
- If
x + yis infinite then the low part is NaN. - If
xoryis infinite or NaN then the low part is NaN. - If
x + yis sub-normal or zero then the low part is +/-0.0.
An invalid result can be identified using
isFinite().The result is the exact double-double representation of the sum.
- Parameters:
x- Addend.y- Addend.- Returns:
- the sum
x + y. - See Also:
ofDifference(double, double)
- If
-
ofDifference
public static DD ofDifference(double x, double y)
Returns aDDwhose value is(x - y). The values are not required to be ordered by magnitude, i.e. the result matches a negation and addition:x - y == -y + x.Computes the same results as
ofSum(a, -b). See that method for details of special cases.An invalid result can be identified using
isFinite().The result is the exact double-double representation of the difference.
- Parameters:
x- Minuend.y- Subtrahend.- Returns:
x - y.- See Also:
ofSum(double, double)
-
ofProduct
public static DD ofProduct(double x, double y)
Returns aDDwhose value is(x * y).This method ignores special handling of non-normal numbers and intermediate overflow within the extended precision computation. This creates the following special cases:
- If either
|x|or|y|multiplied by1 + 2^27is infinite (intermediate overflow) then the low part is NaN. - If
x * yis infinite then the low part is NaN. - If
xoryis infinite or NaN then the low part is NaN. - If
x * yis sub-normal or zero then the low part is +/-0.0.
An invalid result can be identified using
isFinite().Note: Ignoring special cases is a design choice for performance. The method is therefore not a drop-in replacement for
roundOff = Math.fma(x, y, -x * y).The result is the exact double-double representation of the product.
- Parameters:
x- Factor.y- Factor.- Returns:
- the product
x * y.
- If either
-
ofSquare
public static DD ofSquare(double x)
Returns aDDwhose value is(x * x).This method is an optimisation of
multiply(x, x). See that method for details of special cases.An invalid result can be identified using
isFinite().The result is the exact double-double representation of the square.
- Parameters:
x- Factor.- Returns:
- the square
x * x. - See Also:
ofProduct(double, double)
-
fromQuotient
public static DD fromQuotient(double x, double y)
Returns aDDwhose value is(x / y). Ify = 0the result is undefined.This method ignores special handling of non-normal numbers and intermediate overflow within the extended precision computation. This creates the following special cases:
- If either
|x / y|or|y|multiplied by1 + 2^27is infinite (intermediate overflow) then the low part is NaN. - If
x / yis infinite then the low part is NaN. - If
xoryis infinite or NaN then the low part is NaN. - If
x / yis sub-normal or zero, excluding the previous cases, then the low part is +/-0.0.
An invalid result can be identified using
isFinite().The result is the closest double-double representation to the quotient.
- Parameters:
x- Dividend.y- Divisor.- Returns:
- the quotient
x / y.
- If either
-
hi
public double hi()
Gets the first partxof the double-double number(x, xx). In a normalized double-double number this part will have the greatest magnitude.This is equivalent to returning the high-part
xhi for the number(xhi, xlo).- Returns:
- the first part
-
lo
public double lo()
Gets the second partxxof the double-double number(x, xx). In a normalized double-double number this part will have the smallest magnitude.This is equivalent to returning the low part
xlo for the number(xhi, xlo).- Returns:
- the second part
-
isFinite
public boolean isFinite()
Returnstrueif the evaluated sum of the parts is finite.This method is provided as a utility to check the result of a
DDcomputation. Note that for performance theDDclass does not follow IEEE754 arithmetic for infinite and NaN, and does not protect from overflow of intermediate values in multiply and divide operations. If this method returnsfalsefollowingDDarithmetic then the computation is not supported to extended precision.Note: Any number that returns
truemay be converted to the exactBigDecimalvalue.- Returns:
trueif this instance represents a finitedoublevalue.- See Also:
Double.isFinite(double),bigDecimalValue()
-
doubleValue
public double doubleValue()
Get the value as adouble. This is the evaluated sum of the parts.Note that even when the return value is finite, this conversion can lose information about the precision of the
DDvalue.Conversion of a finite
DDcan also be performed using theBigDecimalrepresentation.- Specified by:
doubleValuein classNumber- Returns:
- the value converted to a
double - See Also:
bigDecimalValue()
-
floatValue
public float floatValue()
Get the value as afloat. This is the narrowing primitive conversion of thedoubleValue(). This conversion can lose range, resulting in afloatzero from a nonzerodoubleand afloatinfinity from a finitedouble. AdoubleNaN is converted to afloatNaN and adoubleinfinity is converted to the same-signedfloatinfinity.Note that even when the return value is finite, this conversion can lose information about the precision of the
DDvalue.Conversion of a finite
DDcan also be performed using theBigDecimalrepresentation.- Specified by:
floatValuein classNumber- Returns:
- the value converted to a
float - See Also:
bigDecimalValue()
-
intValue
public int intValue()
Get the value as anint. This conversion discards the fractional part of the number and effectively rounds the value to the closest whole number in the direction of zero. This is the equivalent of a cast of a floating-point number to an integer, for example(int) -2.75 => -2.Note that this conversion can lose information about the precision of the
DDvalue.Special cases:
- If the
DDvalue is infinite the result isInteger.MAX_VALUE. - If the
DDvalue is -infinite the result isInteger.MIN_VALUE. - If the
DDvalue is NaN the result is 0.
Conversion of a finite
DDcan also be performed using theBigDecimalrepresentation. Note thatBigDecimalconversion rounds to theBigIntegerwhole number representation and returns the low-order 32-bits. Numbers too large for anintmay change sign. This method ensures the sign is correct by directly rounding to anintand returning the respective upper or lower limit for numbers too large for anint.- Specified by:
intValuein classNumber- Returns:
- the value converted to an
int - See Also:
bigDecimalValue()
- If the
-
longValue
public long longValue()
Get the value as along. This conversion discards the fractional part of the number and effectively rounds the value to the closest whole number in the direction of zero. This is the equivalent of a cast of a floating-point number to an integer, for example(long) -2.75 => -2.Note that this conversion can lose information about the precision of the
DDvalue.Special cases:
- If the
DDvalue is infinite the result isLong.MAX_VALUE. - If the
DDvalue is -infinite the result isLong.MIN_VALUE. - If the
DDvalue is NaN the result is 0.
Conversion of a finite
DDcan also be performed using theBigDecimalrepresentation. Note thatBigDecimalconversion rounds to theBigIntegerwhole number representation and returns the low-order 64-bits. Numbers too large for alongmay change sign. This method ensures the sign is correct by directly rounding to alongand returning the respective upper or lower limit for numbers too large for along.- Specified by:
longValuein classNumber- Returns:
- the value converted to an
int - See Also:
bigDecimalValue()
- If the
-
bigDecimalValue
public BigDecimal bigDecimalValue()
Get the value as aBigDecimal. This is the evaluated sum of the parts; the conversion is exact.The conversion will raise a
NumberFormatExceptionif the number is non-finite.- Returns:
- the double-double as a
BigDecimal. - Throws:
NumberFormatException- if any part of the number isinfiniteorNaN- See Also:
BigDecimal
-
negate
public DD negate()
Returns aDDwhose value is the negation of both parts of double-double number.
-
abs
public DD abs()
Returns aDDwhose value is the absolute value of the number(x, xx)This method assumes that the low partxxis the smaller magnitude.Cases:
- If the
xvalue is negative the result is(-x, -xx). - If the
xvalue is +/- 0.0 the result is(0.0, 0.0); this will remove sign information from the round-off component assumed to be zero. - Otherwise the result is
this.
- If the
-
floor
public DD floor()
Returns the largest (closest to positive infinity)DDvalue that is less than or equal tothisnumber(x, xx)and is equal to a mathematical integer.This method may change the representation of zero and non-finite values; the result is equivalent to
Math.floor(x)and thexxpart is ignored.Cases:
- If
xis NaN, then the result is(NaN, 0). - If
xis infinite, then the result is(x, 0). - If
xis +/-0.0, then the result is(x, 0). - If
x != Math.floor(x), then the result is(Math.floor(x), 0). - Otherwise the result is the
DDvalue equal to the sumMath.floor(x) + Math.floor(xx).
The result may generate a high part smaller (closer to negative infinity) than
Math.floor(x)ifxis a representable integer and thexxvalue is negative.- Returns:
- the largest (closest to positive infinity) value that is less than or equal
to
thisand is equal to a mathematical integer - See Also:
Math.floor(double),isFinite()
- If
-
ceil
public DD ceil()
Returns the smallest (closest to negative infinity)DDvalue that is greater than or equal tothisnumber(x, xx)and is equal to a mathematical integer.This method may change the representation of zero and non-finite values; the result is equivalent to
Math.ceil(x)and thexxpart is ignored.Cases:
- If
xis NaN, then the result is(NaN, 0). - If
xis infinite, then the result is(x, 0). - If
xis +/-0.0, then the result is(x, 0). - If
x != Math.ceil(x), then the result is(Math.ceil(x), 0). - Otherwise the result is the
DDvalue equal to the sumMath.ceil(x) + Math.ceil(xx).
The result may generate a high part larger (closer to positive infinity) than
Math.ceil(x)ifxis a representable integer and thexxvalue is positive.- Returns:
- the smallest (closest to negative infinity) value that is greater than or equal
to
thisand is equal to a mathematical integer - See Also:
Math.ceil(double),isFinite()
- If
-
add
public DD add(double y)
Returns aDDwhose value is(this + y).This computes the same result as
add(DD.of(y)).The computed result is within 2 eps of the exact result where eps is 2-106.
- Parameters:
y- Value to be added to this number.- Returns:
this + y.- See Also:
add(DD)
-
add
public DD add(DD y)
Returns aDDwhose value is(this + y).The computed result is within 4 eps of the exact result where eps is 2-106.
-
subtract
public DD subtract(double y)
Returns aDDwhose value is(this - y).This computes the same result as
add(-y).The computed result is within 2 eps of the exact result where eps is 2-106.
- Parameters:
y- Value to be subtracted from this number.- Returns:
this - y.- See Also:
subtract(DD)
-
subtract
public DD subtract(DD y)
Returns aDDwhose value is(this - y).This computes the same result as
add(y.negate()).The computed result is within 4 eps of the exact result where eps is 2-106.
- Specified by:
subtractin interfaceNativeOperators<DD>- Parameters:
y- Value to be subtracted from this number.- Returns:
this - y.
-
multiply
public DD multiply(double y)
Returns aDDwhose value isthis * y.This computes the same result as
multiply(DD.of(y)).The computed result is within 4 eps of the exact result where eps is 2-106.
- Parameters:
y- Factor.- Returns:
this * y.- See Also:
multiply(DD)
-
multiply
public DD multiply(DD y)
Returns aDDwhose value isthis * y.The computed result is within 4 eps of the exact result where eps is 2-106.
- Specified by:
multiplyin interfaceMultiplication<DD>- Parameters:
y- Factor.- Returns:
this * y.
-
square
public DD square()
Returns aDDwhose value isthis * this.This method is an optimisation of
multiply(this).The computed result is within 4 eps of the exact result where eps is 2-106.
- Returns:
this2- See Also:
multiply(DD)
-
divide
public DD divide(double y)
Returns aDDwhose value is(this / y). Ify = 0the result is undefined.The computed result is within 1 eps of the exact result where eps is 2-106.
- Parameters:
y- Divisor.- Returns:
this / y.
-
divide
public DD divide(DD y)
Returns aDDwhose value is(this / y). Ify = 0the result is undefined.The computed result is within 4 eps of the exact result where eps is 2-106.
- Specified by:
dividein interfaceNativeOperators<DD>- Parameters:
y- Divisor.- Returns:
this / y.
-
reciprocal
public DD reciprocal()
Compute the reciprocal ofthis. Ifthisvalue is zero the result is undefined.The computed result is within 4 eps of the exact result where eps is 2-106.
- Specified by:
reciprocalin interfaceMultiplication<DD>- Returns:
this-1
-
sqrt
public DD sqrt()
Compute the square root ofthisnumber(x, xx).Uses the result
Math.sqrt(x)if that result is not a finite normalizeddouble.Special cases:
- If
xis NaN or less than zero, then the result is(NaN, 0). - If
xis positive infinity, then the result is(+infinity, 0). - If
xis positive zero or negative zero, then the result is(x, 0).
The computed result is within 4 eps of the exact result where eps is 2-106.
- Returns:
sqrt(this)- See Also:
Math.sqrt(double),Double.MIN_NORMAL
- If
-
scalb
public DD scalb(int exp)
Multiplythisnumber(x, xx)by an integral power of two.(y, yy) = (x, xx) * 2^exp
The result is rounded as if performed by a single correctly rounded floating-point multiply. This performs the same result as:
y = Math.scalb(x, exp); yy = Math.scalb(xx, exp);
The implementation computes using a single multiplication if
expis in[-1022, 1023]. Otherwise the parts(x, xx)are scaled by repeated multiplication by power-of-two factors. The result is exact unless the scaling generates sub-normal parts; in this case precision may be lost by a single rounding.- Parameters:
exp- Power of two scale factor.- Returns:
- the result
- See Also:
Math.scalb(double, int),frexp(int[])
-
frexp
public DD frexp(int[] exp)
Convertthisnumberxto fractionalfand integral2^expcomponents.x = f * 2^exp
The combined fractional part (f, ff) is in the range
[0.5, 1).Special cases:
- If
xis zero, then the normalized fraction is zero and the exponent is zero. - If
xis NaN, then the normalized fraction is NaN and the exponent is unspecified. - If
xis infinite, then the normalized fraction is infinite and the exponent is unspecified. - If high-part
xis an exact power of 2 and the low-partxxhas an opposite signed non-zero magnitude then fraction high-partfwill be+/-1such that the double-double number is in the range[0.5, 1).
This is named using the equivalent function in the standard C math.h library.
- Parameters:
exp- Power of two scale factor (integral exponent).- Returns:
- Fraction part.
- See Also:
Math.getExponent(double),scalb(int), C math.h frexp
- If
-
pow
public DD pow(int n)
Computethisnumber(x, xx)raised to the powern.Special cases:
- If
xis not a finite normalizeddouble, the low partxxis ignored and the result isMath.pow(x, n). - If
n = 0the result is(1, 0). - If
n = 1the result is(x, xx). - If
n = -1the result is thereciprocal. - If the computation overflows the result is undefined.
Computation uses multiplication by factors generated by repeat squaring of the value. These multiplications have no special case handling for overflow; in the event of overflow the result is undefined. The
pow(int, long[])method can be used to generate a scaled fraction result for any finiteDDnumber and exponent.The computed result is approximately
16 * (n - 1) * epsof the exact result where eps is 2-106.- Specified by:
powin interfaceNativeOperators<DD>- Parameters:
n- Exponent.- Returns:
thisn- See Also:
Math.pow(double, double),pow(int, long[]),isFinite()
- If
-
pow
public DD pow(int n, long[] exp)
Computethisnumberxraised to the powern.The value is returned as fractional
fand integral2^expcomponents.(x+xx)^n = (f+ff) * 2^exp
The combined fractional part (f, ff) is in the range
[0.5, 1).Special cases:
- If
(x, xx)is zero the high part of the fractional part is computed usingMath.pow(x, n)and the exponent is 0. - If
n = 0the fractional part is 0.5 and the exponent is 1. - If
(x, xx)is an exact power of 2 the fractional part is 0.5 and the exponent is the power of 2 minus 1. - If the result high-part is an exact power of 2 and the low-part has an opposite
signed non-zero magnitude then the fraction high-part
fwill be+/-1such that the double-double number is in the range[0.5, 1). - If the argument is not finite then a fractional representation is not possible. In this case the fraction and the scale factor is undefined.
The computed result is approximately
16 * (n - 1) * epsof the exact result where eps is 2-106.- Parameters:
n- Power.exp- Result power of two scale factor (integral exponent).- Returns:
- Fraction part.
- See Also:
frexp(int[])
- If
-
equals
public boolean equals(Object other)
Test for equality with another object. If the other object is aDDthen a comparison is made of the parts; otherwisefalseis returned.If both parts of two double-double numbers are numerically equivalent the two
DDobjects are considered to be equal. For this purpose, twodoublevalues are considered to be the same if and only if the method callDouble.doubleToLongBits(value + 0.0)returns the identicallongwhen applied to each value. This provides numeric equality of different representations of zero as per-0.0 == 0.0, and equality ofNaNvalues.Note that in most cases, for two instances of class
DD,xandy, the value ofx.equals(y)istrueif and only ifx.hi() == y.hi() && x.lo() == y.lo()also has the value
true. However, there are exceptions:- Instances that contain
NaNvalues in the same part are considered to be equal for that part, even thoughDouble.NaN == Double.NaNhas the valuefalse. - Instances that share a
NaNvalue in one part but have different values in the other part are not considered equal.
The behavior is the same as if the components of the two double-double numbers were passed to
Arrays.equals(double[], double[]):Arrays.equals(new double[]{x.hi() + 0.0, x.lo() + 0.0}, new double[]{y.hi() + 0.0, y.lo() + 0.0});Note: Addition of
0.0converts signed representations of zero values-0.0and0.0to a canonical0.0.- Overrides:
equalsin classObject- Parameters:
other- Object to test for equality with this instance.- Returns:
trueif the objects are equal,falseif object isnull, not an instance ofDD, or not equal to this instance.- See Also:
Double.doubleToLongBits(double),Arrays.equals(double[], double[])
- Instances that contain
-
hashCode
public int hashCode()
Gets a hash code for the double-double number.The behavior is the same as if the parts of the double-double number were passed to
Arrays.hashCode(double[]):Arrays.hashCode(new double[] {hi() + 0.0, lo() + 0.0})Note: Addition of
0.0provides the same hash code for different signed representations of zero values-0.0and0.0.- Overrides:
hashCodein classObject- Returns:
- A hash code value for this object.
- See Also:
Arrays.hashCode(double[])
-
toString
public String toString()
Returns a string representation of the double-double number.The string will represent the numeric values of the parts. The values are split by a separator and surrounded by parentheses.
The format for a double-double number is
"(x,xx)", withxandxxconverted as if usingDouble.toString(double).Note: A numerical string representation of a finite double-double number can be generated by conversion to a
BigDecimalbefore formatting.- Overrides:
toStringin classObject- Returns:
- A string representation of the double-double number.
- See Also:
Double.toString(double),bigDecimalValue()
-
zero
public DD zero()
Identity element.Note: Addition of this value with any element
amay not create an element equal toaif the element contains sign zeros. In this case the magnitude of the result will be identical.
-
isZero
public boolean isZero()
Check if this is a neutral element of addition, i.e.this.add(a)returnsaor an element representing the same value asa.The default implementation calls
equals(zero()). Implementations may want to employ more a efficient method. This may even be required if an implementation has multiple representations ofzeroand itsequalsmethod differentiates between them.- Specified by:
isZeroin interfaceAddition<DD>- Returns:
trueifthisis a neutral element of addition.- See Also:
Addition.zero()
-
one
public DD one()
Identity element.Note: Multiplication of this value with any element
amay not create an element equal toaif the element contains sign zeros. In this case the magnitude of the result will be identical.- Specified by:
onein interfaceMultiplication<DD>- Returns:
- the field element such that for all
a,one().multiply(a).equals(a)istrue.
-
isOne
public boolean isOne()
Check if this is a neutral element of multiplication, i.e.this.multiply(a)returnsaor an element representing the same value asa.The default implementation calls
equals(one()). Implementations may want to employ more a efficient method. This may even be required if an implementation has multiple representations ofoneand itsequalsmethod differentiates between them.- Specified by:
isOnein interfaceMultiplication<DD>- Returns:
trueifthisis a neutral element of multiplication.- See Also:
Multiplication.one()
-
multiply
public DD multiply(int n)
Repeated addition.This computes the same result as
multiply((double) y).- Specified by:
multiplyin interfaceNativeOperators<DD>- Parameters:
n- Number of times to addthisto itself.- Returns:
n * this.- See Also:
multiply(double)
-
-