Class Double
- All Implemented Interfaces:
Serializable,Comparable<Double>,Constable,ConstantDesc
Double class is the wrapper class for values of the primitive
type double. An object of type Double contains a
single field whose type is double.
In addition, this class provides several methods for converting a
double to a String and a
String to a double, as well as other
constants and methods useful when dealing with a
double.
This is a value-based class; programmers should treat instances that are equal as interchangeable and should not use instances for synchronization, or unpredictable behavior may occur. For example, in a future release, synchronization may fail.
Floating-point Equality, Equivalence, and Comparison
IEEE 754 floating-point values include finite nonzero values, signed zeros (+0.0 and -0.0), signed infinities
(positive infinity and
negative infinity), and
NaN (not-a-number).
An equivalence relation on a set of values is a boolean
relation on pairs of values that is reflexive, symmetric, and
transitive. For more discussion of equivalence relations and object
equality, see the Object.equals
specification. An equivalence relation partitions the values it
operates over into sets called equivalence classes. All the
members of the equivalence class are equal to each other under the
relation. An equivalence class may contain only a single member. At
least for some purposes, all the members of an equivalence class
are substitutable for each other. In particular, in a numeric
expression equivalent values can be substituted for one
another without changing the result of the expression, meaning
changing the equivalence class of the result of the expression.
Notably, the built-in == operation on floating-point
values is not an equivalence relation. Despite not
defining an equivalence relation, the semantics of the IEEE 754
== operator were deliberately designed to meet other needs
of numerical computation. There are two exceptions where the
properties of an equivalence relation are not satisfied by
== on floating-point values:
- If
v1andv2are both NaN, thenv1 == v2has the valuefalse. Therefore, for two NaN arguments the reflexive property of an equivalence relation is not satisfied by the==operator. - If
v1represents+0.0whilev2represents-0.0, or vice versa, thenv1 == v2has the valuetrueeven though+0.0and-0.0are distinguishable under various floating-point operations. For example,1.0/+0.0evaluates to positive infinity while1.0/-0.0evaluates to negative infinity and positive infinity and negative infinity are neither equal to each other nor equivalent to each other. Thus, while a signed zero input most commonly determines the sign of a zero result, because of dividing by zero,+0.0and-0.0may not be substituted for each other in general. The sign of a zero input also has a non-substitutable effect on the result of some math library methods.
For ordered comparisons using the built-in comparison operators
(<, <=, etc.), NaN values have another anomalous
situation: a NaN is neither less than, nor greater than, nor equal
to any value, including itself. This means the trichotomy of
comparison does not hold.
To provide the appropriate semantics for equals and
compareTo methods, those methods cannot simply be wrappers
around == or ordered comparison operations. Instead, equals uses representation
equivalence, defining NaN arguments to be equal to each other,
restoring reflexivity, and defining +0.0 to not be
equal to -0.0. For comparisons, compareTo defines a total order where -0.0 is less than
+0.0 and where a NaN is equal to itself and considered
greater than positive infinity.
The operational semantics of equals and
compareTo are expressed in terms of bit-wise converting the floating-point values to integral values.
The natural ordering implemented by compareTo is consistent with equals. That
is, two objects are reported as equal by equals if and only
if compareTo on those objects returns zero.
The adjusted behaviors defined for equals and
compareTo allow instances of wrapper classes to work properly with
conventional data structures. For example, defining NaN
values to be equals to one another allows NaN to be used as
an element of a HashSet or as the key of
a HashMap. Similarly, defining
compareTo as a total ordering, including +0.0,
-0.0, and NaN, allows instances of wrapper classes to be used as
elements of a SortedSet or as keys of a
SortedMap.
Comparing numerical equality to various useful equivalence relations that can be defined over floating-point values:
- numerical equality (
==operator): (Not an equivalence relation) - Two floating-point values represent the same extended real
number. The extended real numbers are the real numbers augmented
with positive infinity and negative infinity. Under numerical
equality,
+0.0and-0.0are equal since they both map to the same real value, 0. A NaN does not map to any real number and is not equal to any value, including itself. - bit-wise equivalence:
- The bits of the two floating-point values are the same. This
equivalence relation for
doublevaluesaandbis implemented by the expressionDouble.doubleToRawLongBits(a) == Double.doubleToRawLongBits(b)
Under this relation,+0.0and-0.0are distinguished from each other and every bit pattern encoding a NaN is distinguished from every other bit pattern encoding a NaN. - representation equivalence:
- The two floating-point values represent the same IEEE 754
datum. In particular, for finite values, the sign, exponent, and significand components of the floating-point values
are the same. Under this relation:
-
+0.0and-0.0are distinguished from each other. - every bit pattern encoding a NaN is considered equivalent to each other
- positive infinity is equivalent to positive infinity; negative infinity is equivalent to negative infinity.
Double.doubleToLongBits(a) == Double.doubleToLongBits(b)Double.valueOf(a).equals(Double.valueOf(b))Double.compare(a, b) == 0
-
a and b, if
neither of a and b is zero or NaN, then the three
relations numerical equality, bit-wise equivalence, and
representation equivalence of a and b have the same
true/false value. In other words, for binary
floating-point values, the three relations only differ if at least
one argument is zero or NaN.
Decimal ↔ Binary Conversion Issues
Many surprising results of binary floating-point arithmetic trace back to aspects of decimal to binary conversion and binary to decimal conversion. While integer values can be exactly represented in any base, which fractional values can be exactly represented in a base is a function of the base. For example, in base 10, 1/3 is a repeating fraction (0.33333....); but in base 3, 1/3 is exactly 0.1(3), that is 1 × 3-1. Similarly, in base 10, 1/10 is exactly representable as 0.1 (1 × 10-1), but in base 2, it is a repeating fraction (0.0001100110011...(2)).Values of the float type have 24
bits of precision and values of the double type have
53 bits of precision. Therefore, since 0.1
is a repeating fraction in base 2 with a four-bit repeat,
0.1f != 0.1d. In more detail, including hexadecimal
floating-point literals:
- The exact numerical value of
0.1f(0x1.99999a0000000p-4f) is 0.100000001490116119384765625. - The exact numerical value of
0.1d(0x1.999999999999ap-4d) is 0.1000000000000000055511151231257827021181583404541015625.
float and double values,
respectively, to the numerical value of 0.1. These results are
consistent with a float value having the equivalent of 6 to
9 digits of decimal precision and a double value having the
equivalent of 15 to 17 digits of decimal precision. (The
equivalent precision varies according to the different relative
densities of binary and decimal values at different points along the
real number line.)
This representation hazard of decimal fractions is one reason to
use caution when storing monetary values as float or
double. Alternatives include:
- using
BigDecimalto store decimal fractional values exactly - scaling up so the monetary value is an integer — for example, multiplying by 100 if the value is denominated in cents or multiplying by 1000 if the value is denominated in mills — and then storing that scaled value in an integer type
For each finite floating-point value and a given floating-point
type, there is a contiguous region of the real number line which
maps to that value. Under the default round to nearest rounding
policy (JLS 15.4), this contiguous region for a value is
typically one ulp (unit in the last place)
wide and centered around the exactly representable value. (At
exponent boundaries, the region is asymmetrical and larger on the
side with the larger exponent.) For example, for 0.1f, the
region can be computed as follows:
// Numeric values listed are exact values
oneTenthApproxAsFloat = 0.100000001490116119384765625;
ulpOfoneTenthApproxAsFloat = Math.ulp(0.1f) = 7.450580596923828125E-9;
// Numeric range that is converted to the float closest to 0.1, _excludes_ endpoints
(oneTenthApproxAsFloat - ½ulpOfoneTenthApproxAsFloat, oneTenthApproxAsFloat + ½ulpOfoneTenthApproxAsFloat) =
(0.0999999977648258209228515625, 0.1000000052154064178466796875)
In particular, a correctly rounded decimal to binary conversion
of any string representing a number in this range, say by Float.parseFloat(String), will be converted to the same value:
Float.parseFloat("0.0999999977648258209228515625000001"); // rounds up to oneTenthApproxAsFloat
Float.parseFloat("0.099999998"); // rounds up to oneTenthApproxAsFloat
Float.parseFloat("0.1"); // rounds up to oneTenthApproxAsFloat
Float.parseFloat("0.100000001490116119384765625"); // exact conversion
Float.parseFloat("0.100000005215406417846679687"); // rounds down to oneTenthApproxAsFloat
Float.parseFloat("0.100000005215406417846679687499999"); // rounds down to oneTenthApproxAsFloat
Similarly, an analogous range can be constructed for the
double type based on the exact value of double
approximation to 0.1d and the numerical value of
Math.ulp(0.1d) and likewise for other particular numerical values
in the float and double types.
As seen in the above conversions, compared to the exact numerical value the operation would have without rounding, the same floating-point value as a result can be:
- greater than the exact result
- equal to the exact result
- less than the exact result
0.1f + 0.1f + 0.1f + 0.1f + 0.1f + 0.1f + 0.1f + 0.1f + 0.1f + 0.1f;
// Numerical value of computed sum: 1.00000011920928955078125,
// the next floating-point value larger than 1.0f, equal to Math.nextUp(1.0f).
0.1d + 0.1d + 0.1d + 0.1d + 0.1d + 0.1d + 0.1d + 0.1d + 0.1d + 0.1d;
// Numerical value of computed sum: 0.99999999999999988897769753748434595763683319091796875,
// the next floating-point value smaller than 1.0d, equal to Math.nextDown(1.0d).
double d = 0.0;
while (d != 1.0) { // Surprising infinite loop
d += 0.1; // Sum never _exactly_ equals 1.0
}
double d = 0.0;
for (int i = 0; i < 10; i++) {
d += 0.1;
} // Value of d is equal to Math.nextDown(1.0).
<, <=, >, >=):
double d = 0.0;
while (d <= 1.0) {
d += 0.1;
} // Value of d approximately 1.0999999999999999
- See Java Language Specification:
-
4.2.3 Floating-Point Types and Values
4.2.4 Floating-Point Operations
15.21.1 Numerical Equality Operators == and !=
15.20.1 Numerical Comparison Operators<,<=,>, and>= - Since:
- 1.0
- External Specifications
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final intThe number of bytes used to represent adoublevalue, 8.static final intMaximum exponent a finitedoublevariable may have, 1023.static final doubleA constant holding the largest positive finite value of typedouble, (2-2-52)·21023.static final intMinimum exponent a normalizeddoublevariable may have, -1022.static final doubleA constant holding the smallest positive normal value of typedouble, 2-1022.static final doubleA constant holding the smallest positive nonzero value of typedouble, 2-1074.static final doubleA constant holding a Not-a-Number (NaN) value of typedouble.static final doubleA constant holding the negative infinity of typedouble.static final doubleA constant holding the positive infinity of typedouble.static final intThe number of bits in the significand of adoublevalue, 53.static final intThe number of bits used to represent adoublevalue, 64.TheClassinstance representing the primitive typedouble. -
Constructor Summary
ConstructorsConstructorDescriptionDouble(double value) Deprecated, for removal: This API element is subject to removal in a future version.It is rarely appropriate to use this constructor.Deprecated, for removal: This API element is subject to removal in a future version.It is rarely appropriate to use this constructor. -
Method Summary
Modifier and TypeMethodDescriptionbyteReturns the value of thisDoubleas abyteafter a narrowing primitive conversion.static intcompare(double d1, double d2) Compares the two specifieddoublevalues.intCompares twoDoubleobjects numerically.Returns anOptionalcontaining the nominal descriptor for this instance, which is the instance itself.static longdoubleToLongBits(double value) Returns a representation of the specified floating-point value according to the IEEE 754 floating-point "double format" bit layout.static longdoubleToRawLongBits(double value) Returns a representation of the specified floating-point value according to the IEEE 754 floating-point "double format" bit layout, preserving Not-a-Number (NaN) values.doubleReturns thedoublevalue of thisDoubleobject.booleanCompares this object against the specified object.floatReturns the value of thisDoubleas afloatafter a narrowing primitive conversion.inthashCode()Returns a hash code for thisDoubleobject.static inthashCode(double value) Returns a hash code for adoublevalue; compatible withDouble.hashCode().intintValue()Returns the value of thisDoubleas anintafter a narrowing primitive conversion.static booleanisFinite(double d) Returnstrueif the argument is a finite floating-point value; returnsfalseotherwise (for NaN and infinity arguments).booleanReturnstrueif thisDoublevalue is infinitely large in magnitude,falseotherwise.static booleanisInfinite(double v) Returnstrueif the specified number is infinitely large in magnitude,falseotherwise.booleanisNaN()Returnstrueif thisDoublevalue is a Not-a-Number (NaN),falseotherwise.static booleanisNaN(double v) Returnstrueif the specified number is a Not-a-Number (NaN) value,falseotherwise.static doublelongBitsToDouble(long bits) Returns thedoublevalue corresponding to a given bit representation.longReturns the value of thisDoubleas alongafter a narrowing primitive conversion.static doublemax(double a, double b) Returns the greater of twodoublevalues as if by callingMath.max.static doublemin(double a, double b) Returns the smaller of twodoublevalues as if by callingMath.min.static doubleReturns a newdoubleinitialized to the value represented by the specifiedString, as performed by thevalueOfmethod of classDouble.Resolves this instance as aConstantDesc, the result of which is the instance itself.shortReturns the value of thisDoubleas ashortafter a narrowing primitive conversion.static doublesum(double a, double b) Adds twodoublevalues together as per the + operator.static StringtoHexString(double d) Returns a hexadecimal string representation of thedoubleargument.toString()Returns a string representation of thisDoubleobject.static StringtoString(double d) Returns a string representation of thedoubleargument.static DoublevalueOf(double d) Returns aDoubleinstance representing the specifieddoublevalue.static DoubleReturns aDoubleobject holding thedoublevalue represented by the argument strings.
-
Field Details
-
POSITIVE_INFINITY
public static final double POSITIVE_INFINITYA constant holding the positive infinity of typedouble. It is equal to the value returned byDouble.longBitsToDouble(0x7ff0000000000000L).- See Also:
-
NEGATIVE_INFINITY
public static final double NEGATIVE_INFINITYA constant holding the negative infinity of typedouble. It is equal to the value returned byDouble.longBitsToDouble(0xfff0000000000000L).- See Also:
-
NaN
public static final double NaNA constant holding a Not-a-Number (NaN) value of typedouble. It is equivalent to the value returned byDouble.longBitsToDouble(0x7ff8000000000000L).- See Also:
-
MAX_VALUE
public static final double MAX_VALUEA constant holding the largest positive finite value of typedouble, (2-2-52)·21023. It is equal to the hexadecimal floating-point literal0x1.fffffffffffffP+1023and also equal toDouble.longBitsToDouble(0x7fefffffffffffffL).- See Also:
-
MIN_NORMAL
public static final double MIN_NORMALA constant holding the smallest positive normal value of typedouble, 2-1022. It is equal to the hexadecimal floating-point literal0x1.0p-1022and also equal toDouble.longBitsToDouble(0x0010000000000000L).- Since:
- 1.6
- See Also:
-
MIN_VALUE
public static final double MIN_VALUEA constant holding the smallest positive nonzero value of typedouble, 2-1074. It is equal to the hexadecimal floating-point literal0x0.0000000000001P-1022and also equal toDouble.longBitsToDouble(0x1L).- See Also:
-
SIZE
public static final int SIZEThe number of bits used to represent adoublevalue, 64.- Since:
- 1.5
- See Also:
-
PRECISION
public static final int PRECISIONThe number of bits in the significand of adoublevalue, 53. This is the parameter N in section 4.2.3 of The Java Language Specification.- Since:
- 19
- See Also:
-
MAX_EXPONENT
public static final int MAX_EXPONENTMaximum exponent a finitedoublevariable may have, 1023. It is equal to the value returned byMath.getExponent(Double.MAX_VALUE).- Since:
- 1.6
- See Also:
-
MIN_EXPONENT
public static final int MIN_EXPONENTMinimum exponent a normalizeddoublevariable may have, -1022. It is equal to the value returned byMath.getExponent(Double.MIN_NORMAL).- Since:
- 1.6
- See Also:
-
BYTES
public static final int BYTESThe number of bytes used to represent adoublevalue, 8.- Since:
- 1.8
- See Also:
-
TYPE
-
-
Constructor Details
-
Double
Deprecated, for removal: This API element is subject to removal in a future version.It is rarely appropriate to use this constructor. The static factoryvalueOf(double)is generally a better choice, as it is likely to yield significantly better space and time performance.Constructs a newly allocatedDoubleobject that represents the primitivedoubleargument.- Parameters:
value- the value to be represented by theDouble.
-
Double
Deprecated, for removal: This API element is subject to removal in a future version.It is rarely appropriate to use this constructor. UseparseDouble(String)to convert a string to adoubleprimitive, or usevalueOf(String)to convert a string to aDoubleobject.Constructs a newly allocatedDoubleobject that represents the floating-point value of typedoublerepresented by the string. The string is converted to adoublevalue as if by thevalueOfmethod.- Parameters:
s- a string to be converted to aDouble.- Throws:
NumberFormatException- if the string does not contain a parsable number.
-
-
Method Details
-
toString
Returns a string representation of thedoubleargument. All characters mentioned below are ASCII characters.- If the argument is NaN, the result is the string
"
NaN". - Otherwise, the result is a string that represents the sign and
magnitude (absolute value) of the argument. If the sign is negative,
the first character of the result is '
-' ('\u002D'); if the sign is positive, no sign character appears in the result. As for the magnitude m:- If m is infinity, it is represented by the characters
"Infinity"; thus, positive infinity produces the result"Infinity"and negative infinity produces the result"-Infinity". - If m is zero, it is represented by the characters
"0.0"; thus, negative zero produces the result"-0.0"and positive zero produces the result"0.0". - Otherwise m is positive and finite.
It is converted to a string in two stages:
- Selection of a decimal: A well-defined decimal dm is selected to represent m. This decimal is (almost always) the shortest one that rounds to m according to the round to nearest rounding policy of IEEE 754 floating-point arithmetic.
- Formatting as a string: The decimal dm is formatted as a string, either in plain or in computerized scientific notation, depending on its value.
- If m is infinity, it is represented by the characters
A decimal is a number of the form s×10i for some (unique) integers s > 0 and i such that s is not a multiple of 10. These integers are the significand and the exponent, respectively, of the decimal. The length of the decimal is the (unique) positive integer n meeting 10n-1 ≤ s < 10n.
The decimal dm for a finite positive m is defined as follows:
- Let R be the set of all decimals that round to m according to the usual round to nearest rounding policy of IEEE 754 floating-point arithmetic.
- Let p be the minimal length over all decimals in R.
- When p ≥ 2, let T be the set of all decimals in R with length p. Otherwise, let T be the set of all decimals in R with length 1 or 2.
- Define dm as the decimal in T that is closest to m. Or if there are two such decimals in T, select the one with the even significand.
The (uniquely) selected decimal dm is then formatted. Let s, i and n be the significand, exponent and length of dm, respectively. Further, let e = n + i - 1 and let s1…sn be the usual decimal expansion of s. Note that s1 ≠ 0 and sn ≠ 0. Below, the decimal point
'.'is'\u002E'and the exponent indicator'E'is'\u0045'.- Case -3 ≤ e < 0:
dm is formatted as
0.0…0s1…sn, where there are exactly -(n + i) zeroes between the decimal point and s1. For example, 123 × 10-4 is formatted as0.0123. - Case 0 ≤ e < 7:
- Subcase i ≥ 0:
dm is formatted as
s1…sn
0…0.0, where there are exactly i zeroes between sn and the decimal point. For example, 123 × 102 is formatted as12300.0. - Subcase i < 0:
dm is formatted as
s1…sn+i
.sn+i+1…sn, where there are exactly -i digits to the right of the decimal point. For example, 123 × 10-1 is formatted as12.3.
- Subcase i ≥ 0:
dm is formatted as
s1…sn
- Case e < -3 or e ≥ 7:
computerized scientific notation is used to format
dm.
Here e is formatted as by
Integer.toString(int).- Subcase n = 1:
dm is formatted as
s1
.0Ee. For example, 1 × 1023 is formatted as1.0E23. - Subcase n > 1:
dm is formatted as
s1
.s2…snEe. For example, 123 × 10-21 is formatted as1.23E-19.
- Subcase n = 1:
dm is formatted as
s1
To create localized string representations of a floating-point value, use subclasses of
NumberFormat.- API Note:
- This method corresponds to the general functionality of the
convertToDecimalCharacter operation defined in IEEE 754;
however, that operation is defined in terms of specifying the
number of significand digits used in the conversion.
Code to do such a conversion in the Java platform includes
converting the
doubleto aBigDecimalexactly and then rounding theBigDecimalto the desired number of digits; sample code:double d = 0.1; int digits = 25; BigDecimal bd = new BigDecimal(d); String result = bd.round(new MathContext(digits, RoundingMode.HALF_UP)); // 0.1000000000000000055511151 - Parameters:
d- thedoubleto be converted.- Returns:
- a string representation of the argument.
- If the argument is NaN, the result is the string
"
-
toHexString
Returns a hexadecimal string representation of thedoubleargument. All characters mentioned below are ASCII characters.- If the argument is NaN, the result is the string
"
NaN". - Otherwise, the result is a string that represents the sign
and magnitude of the argument. If the sign is negative, the
first character of the result is '
-' ('\u002D'); if the sign is positive, no sign character appears in the result. As for the magnitude m:- If m is infinity, it is represented by the string
"Infinity"; thus, positive infinity produces the result"Infinity"and negative infinity produces the result"-Infinity". - If m is zero, it is represented by the string
"0x0.0p0"; thus, negative zero produces the result"-0x0.0p0"and positive zero produces the result"0x0.0p0". - If m is a
doublevalue with a normalized representation, substrings are used to represent the significand and exponent fields. The significand is represented by the characters"0x1."followed by a lowercase hexadecimal representation of the rest of the significand as a fraction. Trailing zeros in the hexadecimal representation are removed unless all the digits are zero, in which case a single zero is used. Next, the exponent is represented by"p"followed by a decimal string of the unbiased exponent as if produced by a call toInteger.toStringon the exponent value. - If m is a
doublevalue with a subnormal representation, the significand is represented by the characters"0x0."followed by a hexadecimal representation of the rest of the significand as a fraction. Trailing zeros in the hexadecimal representation are removed. Next, the exponent is represented by"p-1022". Note that there must be at least one nonzero digit in a subnormal significand.
- If m is infinity, it is represented by the string
Examples Floating-point Value Hexadecimal String 1.00x1.0p0-1.0-0x1.0p02.00x1.0p13.00x1.8p10.50x1.0p-10.250x1.0p-2Double.MAX_VALUE0x1.fffffffffffffp1023Minimum Normal Value0x1.0p-1022Maximum Subnormal Value0x0.fffffffffffffp-1022Double.MIN_VALUE0x0.0000000000001p-1022- API Note:
- This method corresponds to the convertToHexCharacter operation defined in IEEE 754.
- Parameters:
d- thedoubleto be converted.- Returns:
- a hex string representation of the argument.
- Since:
- 1.5
- If the argument is NaN, the result is the string
"
-
valueOf
Returns aDoubleobject holding thedoublevalue represented by the argument strings.If
sisnull, then aNullPointerExceptionis thrown.Leading and trailing whitespace characters in
sare ignored. Whitespace is removed as if by theString.trim()method; that is, both ASCII space and control characters are removed. The rest ofsshould constitute a FloatValue as described by the lexical syntax rules:
where Sign, FloatingPointLiteral, HexNumeral, HexDigits, SignedInteger and FloatTypeSuffix are as defined in the lexical structure sections of The Java Language Specification, except that underscores are not accepted between digits. If- FloatValue:
- Signopt
NaN- Signopt
Infinity- Signopt FloatingPointLiteral
- Signopt HexFloatingPointLiteral
- SignedInteger
- Signopt
- HexFloatingPointLiteral:
- HexSignificand BinaryExponent FloatTypeSuffixopt
- HexSignificand:
- HexNumeral
- HexNumeral
.0xHexDigitsopt.HexDigits0XHexDigitsopt.HexDigits - HexNumeral
- BinaryExponent:
- BinaryExponentIndicator SignedInteger
- BinaryExponentIndicator:
pP
sdoes not have the form of a FloatValue, then aNumberFormatExceptionis thrown. Otherwise,sis regarded as representing an exact decimal value in the usual "computerized scientific notation" or as an exact hexadecimal value; this exact numerical value is then conceptually converted to an "infinitely precise" binary value that is then rounded to typedoubleby the usual round-to-nearest rule of IEEE 754 floating-point arithmetic, which includes preserving the sign of a zero value. Note that the round-to-nearest rule also implies overflow and underflow behaviour; if the exact value ofsis large enough in magnitude (greater than or equal to (MAX_VALUE+ulp(MAX_VALUE)/2), rounding todoublewill result in an infinity and if the exact value ofsis small enough in magnitude (less than or equal toMIN_VALUE/2), rounding to float will result in a zero. Finally, after rounding aDoubleobject representing thisdoublevalue is returned.Note that trailing format specifiers, specifiers that determine the type of a floating-point literal (
1.0fis afloatvalue;1.0dis adoublevalue), do not influence the results of this method. In other words, the numerical value of the input string is converted directly to the target floating-point type. The two-step sequence of conversions, string tofloatfollowed byfloattodouble, is not equivalent to converting a string directly todouble. For example, thefloatliteral0.1fis equal to thedoublevalue0.10000000149011612; thefloatliteral0.1frepresents a different numerical value than thedoubleliteral0.1. (The numerical value 0.1 cannot be exactly represented in a binary floating-point number.)To avoid calling this method on an invalid string and having a
NumberFormatExceptionbe thrown, the regular expression below can be used to screen the input string:final String Digits = "(\\p{Digit}+)"; final String HexDigits = "(\\p{XDigit}+)"; // an exponent is 'e' or 'E' followed by an optionally // signed decimal integer. final String Exp = "[eE][+-]?"+Digits; final String fpRegex = ("[\\x00-\\x20]*"+ // Optional leading "whitespace" "[+-]?(" + // Optional sign character "NaN|" + // "NaN" string "Infinity|" + // "Infinity" string // A decimal floating-point string representing a finite positive // number without a leading sign has at most five basic pieces: // Digits . Digits ExponentPart FloatTypeSuffix // // Since this method allows integer-only strings as input // in addition to strings of floating-point literals, the // two sub-patterns below are simplifications of the grammar // productions from section 3.10.2 of // The Java Language Specification. // Digits ._opt Digits_opt ExponentPart_opt FloatTypeSuffix_opt "((("+Digits+"(\\.)?("+Digits+"?)("+Exp+")?)|"+ // . Digits ExponentPart_opt FloatTypeSuffix_opt "(\\.("+Digits+")("+Exp+")?)|"+ // Hexadecimal strings "((" + // 0[xX] HexDigits ._opt BinaryExponent FloatTypeSuffix_opt "(0[xX]" + HexDigits + "(\\.)?)|" + // 0[xX] HexDigits_opt . HexDigits BinaryExponent FloatTypeSuffix_opt "(0[xX]" + HexDigits + "?(\\.)" + HexDigits + ")" + ")[pP][+-]?" + Digits + "))" + "[fFdD]?))" + "[\\x00-\\x20]*");// Optional trailing "whitespace" if (Pattern.matches(fpRegex, myString)) Double.valueOf(myString); // Will not throw NumberFormatException else { // Perform suitable alternative action }- API Note:
- To interpret localized string representations of a
floating-point value, or string representations that have
non-ASCII digits, use
NumberFormat. For example,whereNumberFormat.getInstance(l).parse(s).doubleValue();lis the desired locale, orLocale.ROOTif locale insensitive., This method corresponds to the convertFromDecimalCharacter and convertFromHexCharacter operations defined in IEEE 754. - Parameters:
s- the string to be parsed.- Returns:
- a
Doubleobject holding the value represented by theStringargument. - Throws:
NumberFormatException- if the string does not contain a parsable number.- See Also:
-
valueOf
Returns aDoubleinstance representing the specifieddoublevalue. If a newDoubleinstance is not required, this method should generally be used in preference to the constructorDouble(double), as this method is likely to yield significantly better space and time performance by caching frequently requested values.- Parameters:
d- a double value.- Returns:
- a
Doubleinstance representingd. - Since:
- 1.5
-
parseDouble
Returns a newdoubleinitialized to the value represented by the specifiedString, as performed by thevalueOfmethod of classDouble.- Parameters:
s- the string to be parsed.- Returns:
- the
doublevalue represented by the string argument. - Throws:
NullPointerException- if the string is nullNumberFormatException- if the string does not contain a parsabledouble.- Since:
- 1.2
- See Also:
-
isNaN
public static boolean isNaN(double v) Returnstrueif the specified number is a Not-a-Number (NaN) value,falseotherwise.- API Note:
- This method corresponds to the isNaN operation defined in IEEE 754.
- Parameters:
v- the value to be tested.- Returns:
trueif the value of the argument is NaN;falseotherwise.
-
isInfinite
public static boolean isInfinite(double v) Returnstrueif the specified number is infinitely large in magnitude,falseotherwise.- API Note:
- This method corresponds to the isInfinite operation defined in IEEE 754.
- Parameters:
v- the value to be tested.- Returns:
trueif the value of the argument is positive infinity or negative infinity;falseotherwise.
-
isFinite
public static boolean isFinite(double d) Returnstrueif the argument is a finite floating-point value; returnsfalseotherwise (for NaN and infinity arguments).- API Note:
- This method corresponds to the isFinite operation defined in IEEE 754.
- Parameters:
d- thedoublevalue to be tested- Returns:
trueif the argument is a finite floating-point value,falseotherwise.- Since:
- 1.8
-
isNaN
public boolean isNaN()Returnstrueif thisDoublevalue is a Not-a-Number (NaN),falseotherwise.- Returns:
trueif the value represented by this object is NaN;falseotherwise.
-
isInfinite
public boolean isInfinite()Returnstrueif thisDoublevalue is infinitely large in magnitude,falseotherwise.- Returns:
trueif the value represented by this object is positive infinity or negative infinity;falseotherwise.
-
toString
Returns a string representation of thisDoubleobject. The primitivedoublevalue represented by this object is converted to a string exactly as if by the methodtoStringof one argument. -
byteValue
public byte byteValue()Returns the value of thisDoubleas abyteafter a narrowing primitive conversion.- Overrides:
byteValuein classNumber- Returns:
- the
doublevalue represented by this object converted to typebyte - See Java Language Specification:
-
5.1.3 Narrowing Primitive Conversion
- Since:
- 1.1
-
shortValue
public short shortValue()Returns the value of thisDoubleas ashortafter a narrowing primitive conversion.- Overrides:
shortValuein classNumber- Returns:
- the
doublevalue represented by this object converted to typeshort - See Java Language Specification:
-
5.1.3 Narrowing Primitive Conversion
- Since:
- 1.1
-
intValue
public int intValue()Returns the value of thisDoubleas anintafter a narrowing primitive conversion.- Specified by:
intValuein classNumber- API Note:
- This method corresponds to the convertToIntegerTowardZero operation defined in IEEE 754.
- Returns:
- the
doublevalue represented by this object converted to typeint - See Java Language Specification:
-
5.1.3 Narrowing Primitive Conversion
-
longValue
public long longValue()Returns the value of thisDoubleas alongafter a narrowing primitive conversion.- Specified by:
longValuein classNumber- API Note:
- This method corresponds to the convertToIntegerTowardZero operation defined in IEEE 754.
- Returns:
- the
doublevalue represented by this object converted to typelong - See Java Language Specification:
-
5.1.3 Narrowing Primitive Conversion
-
floatValue
public float floatValue()Returns the value of thisDoubleas afloatafter a narrowing primitive conversion.- Specified by:
floatValuein classNumber- API Note:
- This method corresponds to the convertFormat operation defined in IEEE 754.
- Returns:
- the
doublevalue represented by this object converted to typefloat - See Java Language Specification:
-
5.1.3 Narrowing Primitive Conversion
- Since:
- 1.0
-
doubleValue
public double doubleValue()Returns thedoublevalue of thisDoubleobject.- Specified by:
doubleValuein classNumber- Returns:
- the
doublevalue represented by this object
-
hashCode
public int hashCode()Returns a hash code for thisDoubleobject. The result is the exclusive OR of the two halves of thelonginteger bit representation, exactly as produced by the methoddoubleToLongBits(double), of the primitivedoublevalue represented by thisDoubleobject. That is, the hash code is the value of the expression:
where(int)(v^(v>>>32))vis defined by:long v = Double.doubleToLongBits(this.doubleValue()); -
hashCode
public static int hashCode(double value) Returns a hash code for adoublevalue; compatible withDouble.hashCode().- Parameters:
value- the value to hash- Returns:
- a hash code value for a
doublevalue. - Since:
- 1.8
-
equals
Compares this object against the specified object. The result istrueif and only if the argument is notnulland is aDoubleobject that represents adoublethat has the same value as thedoublerepresented by this object. For this purpose, twodoublevalues are considered to be the same if and only if the methoddoubleToLongBits(double)returns the identicallongvalue when applied to each.- Overrides:
equalsin classObject- API Note:
- This method is defined in terms of
doubleToLongBits(double)rather than the==operator ondoublevalues since the==operator does not define an equivalence relation and to satisfy the equals contract an equivalence relation must be implemented; see this discussion for details of floating-point equality and equivalence. - Parameters:
obj- the reference object with which to compare.- Returns:
trueif this object is the same as the obj argument;falseotherwise.- See Java Language Specification:
-
15.21.1 Numerical Equality Operators == and !=
- See Also:
-
doubleToLongBits
public static long doubleToLongBits(double value) Returns a representation of the specified floating-point value according to the IEEE 754 floating-point "double format" bit layout.Bit 63 (the bit that is selected by the mask
0x8000000000000000L) represents the sign of the floating-point number. Bits 62-52 (the bits that are selected by the mask0x7ff0000000000000L) represent the exponent. Bits 51-0 (the bits that are selected by the mask0x000fffffffffffffL) represent the significand (sometimes called the mantissa) of the floating-point number.If the argument is positive infinity, the result is
0x7ff0000000000000L.If the argument is negative infinity, the result is
0xfff0000000000000L.If the argument is NaN, the result is
0x7ff8000000000000L.In all cases, the result is a
longinteger that, when given to thelongBitsToDouble(long)method, will produce a floating-point value the same as the argument todoubleToLongBits(except all NaN values are collapsed to a single "canonical" NaN value).- Parameters:
value- adoubleprecision floating-point number.- Returns:
- the bits that represent the floating-point number.
-
doubleToRawLongBits
public static long doubleToRawLongBits(double value) Returns a representation of the specified floating-point value according to the IEEE 754 floating-point "double format" bit layout, preserving Not-a-Number (NaN) values.Bit 63 (the bit that is selected by the mask
0x8000000000000000L) represents the sign of the floating-point number. Bits 62-52 (the bits that are selected by the mask0x7ff0000000000000L) represent the exponent. Bits 51-0 (the bits that are selected by the mask0x000fffffffffffffL) represent the significand (sometimes called the mantissa) of the floating-point number.If the argument is positive infinity, the result is
0x7ff0000000000000L.If the argument is negative infinity, the result is
0xfff0000000000000L.If the argument is NaN, the result is the
longinteger representing the actual NaN value. Unlike thedoubleToLongBitsmethod,doubleToRawLongBitsdoes not collapse all the bit patterns encoding a NaN to a single "canonical" NaN value.In all cases, the result is a
longinteger that, when given to thelongBitsToDouble(long)method, will produce a floating-point value the same as the argument todoubleToRawLongBits.- Parameters:
value- adoubleprecision floating-point number.- Returns:
- the bits that represent the floating-point number.
- Since:
- 1.3
-
longBitsToDouble
public static double longBitsToDouble(long bits) Returns thedoublevalue corresponding to a given bit representation. The argument is considered to be a representation of a floating-point value according to the IEEE 754 floating-point "double format" bit layout.If the argument is
0x7ff0000000000000L, the result is positive infinity.If the argument is
0xfff0000000000000L, the result is negative infinity.If the argument is any value in the range
0x7ff0000000000001Lthrough0x7fffffffffffffffLor in the range0xfff0000000000001Lthrough0xffffffffffffffffL, the result is a NaN. No IEEE 754 floating-point operation provided by Java can distinguish between two NaN values of the same type with different bit patterns. Distinct values of NaN are only distinguishable by use of theDouble.doubleToRawLongBitsmethod.In all other cases, let s, e, and m be three values that can be computed from the argument:
Then the floating-point result equals the value of the mathematical expression s·m·2e-1075.int s = ((bits >> 63) == 0) ? 1 : -1; int e = (int)((bits >> 52) & 0x7ffL); long m = (e == 0) ? (bits & 0xfffffffffffffL) << 1 : (bits & 0xfffffffffffffL) | 0x10000000000000L;Note that this method may not be able to return a
doubleNaN with exactly same bit pattern as thelongargument. IEEE 754 distinguishes between two kinds of NaNs, quiet NaNs and signaling NaNs. The differences between the two kinds of NaN are generally not visible in Java. Arithmetic operations on signaling NaNs turn them into quiet NaNs with a different, but often similar, bit pattern. However, on some processors merely copying a signaling NaN also performs that conversion. In particular, copying a signaling NaN to return it to the calling method may perform this conversion. SolongBitsToDoublemay not be able to return adoublewith a signaling NaN bit pattern. Consequently, for somelongvalues,doubleToRawLongBits(longBitsToDouble(start))may not equalstart. Moreover, which particular bit patterns represent signaling NaNs is platform dependent; although all NaN bit patterns, quiet or signaling, must be in the NaN range identified above.- Parameters:
bits- anylonginteger.- Returns:
- the
doublefloating-point value with the same bit pattern.
-
compareTo
Compares twoDoubleobjects numerically. This method imposes a total order onDoubleobjects with two differences compared to the incomplete order defined by the Java language numerical comparison operators (<, <=, ==, >=, >) ondoublevalues.- A NaN is unordered with respect to other
values and unequal to itself under the comparison
operators. This method chooses to define
Double.NaNto be equal to itself and greater than all otherdoublevalues (includingDouble.POSITIVE_INFINITY). - Positive zero and negative zero compare equal
numerically, but are distinct and distinguishable values.
This method chooses to define positive zero (
+0.0d), to be greater than negative zero (-0.0d).
Doubleobjects imposed by this method is consistent with equals; see this discussion for details of floating-point comparison and ordering.- Specified by:
compareToin interfaceComparable<Double>- Parameters:
anotherDouble- theDoubleto be compared.- Returns:
- the value
0ifanotherDoubleis numerically equal to thisDouble; a value less than0if thisDoubleis numerically less thananotherDouble; and a value greater than0if thisDoubleis numerically greater thananotherDouble. - See Java Language Specification:
-
15.20.1 Numerical Comparison Operators
<,<=,>, and>= - Since:
- 1.2
- A NaN is unordered with respect to other
values and unequal to itself under the comparison
operators. This method chooses to define
-
compare
public static int compare(double d1, double d2) Compares the two specifieddoublevalues. The sign of the integer value returned is the same as that of the integer that would be returned by the call:Double.valueOf(d1).compareTo(Double.valueOf(d2))- Parameters:
d1- the firstdoubleto compared2- the seconddoubleto compare- Returns:
- the value
0ifd1is numerically equal tod2; a value less than0ifd1is numerically less thand2; and a value greater than0ifd1is numerically greater thand2. - Since:
- 1.4
-
sum
public static double sum(double a, double b) Adds twodoublevalues together as per the + operator.- API Note:
- This method corresponds to the addition operation defined in IEEE 754.
- Parameters:
a- the first operandb- the second operand- Returns:
- the sum of
aandb - See Java Language Specification:
-
4.2.4 Floating-Point Operations
- Since:
- 1.8
- See Also:
-
max
public static double max(double a, double b) Returns the greater of twodoublevalues as if by callingMath.max.- API Note:
- This method corresponds to the maximum operation defined in IEEE 754.
- Parameters:
a- the first operandb- the second operand- Returns:
- the greater of
aandb - Since:
- 1.8
- See Also:
-
min
public static double min(double a, double b) Returns the smaller of twodoublevalues as if by callingMath.min.- API Note:
- This method corresponds to the minimum operation defined in IEEE 754.
- Parameters:
a- the first operandb- the second operand- Returns:
- the smaller of
aandb. - Since:
- 1.8
- See Also:
-
describeConstable
-
resolveConstantDesc
Resolves this instance as aConstantDesc, the result of which is the instance itself.- Specified by:
resolveConstantDescin interfaceConstantDesc- Parameters:
lookup- ignored- Returns:
- the Double instance
- Since:
- 12
-