Class Double
- All Implemented Interfaces:
Serializable
,Comparable<Double>
,Constable
,ConstantDesc
Double
class wraps a value of the primitive type
double
in an object. 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
v1
andv2
are both NaN, thenv1 == v2
has the valuefalse
. Therefore, for two NaN arguments the reflexive property of an equivalence relation is not satisfied by the==
operator. - If
v1
represents+0.0
whilev2
represents-0.0
, or vice versa, thenv1 == v2
has the valuetrue
even though+0.0
and-0.0
are distinguishable under various floating-point operations. For example,1.0/+0.0
evaluates to positive infinity while1.0/-0.0
evaluates 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.0
and-0.0
may 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.0
and-0.0
are 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
double
valuesa
andb
is implemented by the expressionDouble.doubleTo
Raw
LongBits(a) == Double.doubleTo
Raw
LongBits(b)
Under this relation,+0.0
and-0.0
are 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.0
and-0.0
are 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
BigDecimal
to 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
- See Also:
-
Field Summary
Modifier and TypeFieldDescriptionstatic final int
The number of bytes used to represent adouble
value, 8.static final int
Maximum exponent a finitedouble
variable may have, 1023.static final double
A constant holding the largest positive finite value of typedouble
, (2-2-52)·21023.static final int
Minimum exponent a normalizeddouble
variable may have, -1022.static final double
A constant holding the smallest positive normal value of typedouble
, 2-1022.static final double
A constant holding the smallest positive nonzero value of typedouble
, 2-1074.static final double
A constant holding a Not-a-Number (NaN) value of typedouble
.static final double
A constant holding the negative infinity of typedouble
.static final double
A constant holding the positive infinity of typedouble
.static final int
The number of bits in the significand of adouble
value, 53.static final int
The number of bits used to represent adouble
value, 64.TheClass
instance representing the primitive typedouble
. -
Constructor Summary
ConstructorDescriptionDouble
(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 TypeMethodDescriptionbyte
Returns the value of thisDouble
as abyte
after a narrowing primitive conversion.static int
compare
(double d1, double d2) Compares the two specifieddouble
values.int
Compares twoDouble
objects numerically.Returns anOptional
containing the nominal descriptor for this instance, which is the instance itself.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.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.double
Returns thedouble
value of thisDouble
object.boolean
Compares this object against the specified object.float
Returns the value of thisDouble
as afloat
after a narrowing primitive conversion.int
hashCode()
Returns a hash code for thisDouble
object.static int
hashCode
(double value) Returns a hash code for adouble
value; compatible withDouble.hashCode()
.int
intValue()
Returns the value of thisDouble
as anint
after a narrowing primitive conversion.static boolean
isFinite
(double d) Returnstrue
if the argument is a finite floating-point value; returnsfalse
otherwise (for NaN and infinity arguments).boolean
Returnstrue
if thisDouble
value is infinitely large in magnitude,false
otherwise.static boolean
isInfinite
(double v) Returnstrue
if the specified number is infinitely large in magnitude,false
otherwise.boolean
isNaN()
Returnstrue
if thisDouble
value is a Not-a-Number (NaN),false
otherwise.static boolean
isNaN
(double v) Returnstrue
if the specified number is a Not-a-Number (NaN) value,false
otherwise.static double
longBitsToDouble
(long bits) Returns thedouble
value corresponding to a given bit representation.long
Returns the value of thisDouble
as along
after a narrowing primitive conversion.static double
max
(double a, double b) Returns the greater of twodouble
values as if by callingMath.max
.static double
min
(double a, double b) Returns the smaller of twodouble
values as if by callingMath.min
.static double
Returns a newdouble
initialized to the value represented by the specifiedString
, as performed by thevalueOf
method of classDouble
.Resolves this instance as aConstantDesc
, the result of which is the instance itself.short
Returns the value of thisDouble
as ashort
after a narrowing primitive conversion.static double
sum
(double a, double b) Adds twodouble
values together as per the + operator.static String
toHexString
(double d) Returns a hexadecimal string representation of thedouble
argument.toString()
Returns a string representation of thisDouble
object.static String
toString
(double d) Returns a string representation of thedouble
argument.static Double
valueOf
(double d) Returns aDouble
instance representing the specifieddouble
value.static Double
Returns aDouble
object holding thedouble
value 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+1023
and 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-1022
and 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-1022
and also equal toDouble.longBitsToDouble(0x1L)
.- See Also:
-
SIZE
public static final int SIZEThe number of bits used to represent adouble
value, 64.- Since:
- 1.5
- See Also:
-
PRECISION
public static final int PRECISIONThe number of bits in the significand of adouble
value, 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 finitedouble
variable 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 normalizeddouble
variable 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 adouble
value, 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 allocatedDouble
object that represents the primitivedouble
argument.- 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 adouble
primitive, or usevalueOf(String)
to convert a string to aDouble
object.Constructs a newly allocatedDouble
object that represents the floating-point value of typedouble
represented by the string. The string is converted to adouble
value as if by thevalueOf
method.- 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 thedouble
argument. 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
…0
s1…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
.0E
e. For example, 1 × 1023 is formatted as1.0E23
. - Subcase n > 1:
dm is formatted as
s1
.
s2…snE
e. 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
double
to aBigDecimal
exactly and then rounding theBigDecimal
to 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
- thedouble
to 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 thedouble
argument. 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
double
value 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.toString
on the exponent value. - If m is a
double
value 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.0
0x1.0p0
-1.0
-0x1.0p0
2.0
0x1.0p1
3.0
0x1.8p1
0.5
0x1.0p-1
0.25
0x1.0p-2
Double.MAX_VALUE
0x1.fffffffffffffp1023
Minimum Normal Value
0x1.0p-1022
Maximum Subnormal Value
0x0.fffffffffffffp-1022
Double.MIN_VALUE
0x0.0000000000001p-1022
- API Note:
- This method corresponds to the convertToHexCharacter operation defined in IEEE 754.
- Parameters:
d
- thedouble
to 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 aDouble
object holding thedouble
value represented by the argument strings
.If
s
isnull
, then aNullPointerException
is thrown.Leading and trailing whitespace characters in
s
are ignored. Whitespace is removed as if by theString.trim()
method; that is, both ASCII space and control characters are removed. The rest ofs
should constitute a FloatValue as described by the lexical syntax rules:- FloatValue:
- Signopt
NaN
- Signopt
Infinity
- Signopt FloatingPointLiteral
- Signopt HexFloatingPointLiteral
- SignedInteger
- Signopt
- HexFloatingPointLiteral:
- HexSignificand BinaryExponent FloatTypeSuffixopt
- HexSignificand:
- HexNumeral
- HexNumeral
.
0x
HexDigitsopt.
HexDigits0X
HexDigitsopt.
HexDigits - HexNumeral
- BinaryExponent:
- BinaryExponentIndicator SignedInteger
- BinaryExponentIndicator:
p
P
s
does not have the form of a FloatValue, then aNumberFormatException
is thrown. Otherwise,s
is 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 typedouble
by 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 ofs
is large enough in magnitude (greater than or equal to (MAX_VALUE
+ulp(MAX_VALUE)
/2), rounding todouble
will result in an infinity and if the exact value ofs
is small enough in magnitude (less than or equal toMIN_VALUE
/2), rounding to float will result in a zero. Finally, after rounding aDouble
object representing thisdouble
value is returned.Note that trailing format specifiers, specifiers that determine the type of a floating-point literal (
1.0f
is afloat
value;1.0d
is adouble
value), 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 tofloat
followed byfloat
todouble
, is not equivalent to converting a string directly todouble
. For example, thefloat
literal0.1f
is equal to thedouble
value0.10000000149011612
; thefloat
literal0.1f
represents a different numerical value than thedouble
literal0.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
NumberFormatException
be 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,NumberFormat.getInstance(l).parse(s).doubleValue();
l
is the desired locale, orLocale.ROOT
if locale insensitive., This method corresponds to the convertFromDecimalCharacter and convertFromHexCharacter operations defined in IEEE 754. - Parameters:
s
- the string to be parsed.- Returns:
- a
Double
object holding the value represented by theString
argument. - Throws:
NumberFormatException
- if the string does not contain a parsable number.- See Also:
-
valueOf
Returns aDouble
instance representing the specifieddouble
value. If a newDouble
instance 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
Double
instance representingd
. - Since:
- 1.5
-
parseDouble
Returns a newdouble
initialized to the value represented by the specifiedString
, as performed by thevalueOf
method of classDouble
.- Parameters:
s
- the string to be parsed.- Returns:
- the
double
value 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) Returnstrue
if the specified number is a Not-a-Number (NaN) value,false
otherwise.- API Note:
- This method corresponds to the isNaN operation defined in IEEE 754.
- Parameters:
v
- the value to be tested.- Returns:
true
if the value of the argument is NaN;false
otherwise.
-
isInfinite
public static boolean isInfinite(double v) Returnstrue
if the specified number is infinitely large in magnitude,false
otherwise.- API Note:
- This method corresponds to the isInfinite operation defined in IEEE 754.
- Parameters:
v
- the value to be tested.- Returns:
true
if the value of the argument is positive infinity or negative infinity;false
otherwise.
-
isFinite
public static boolean isFinite(double d) Returnstrue
if the argument is a finite floating-point value; returnsfalse
otherwise (for NaN and infinity arguments).- API Note:
- This method corresponds to the isFinite operation defined in IEEE 754.
- Parameters:
d
- thedouble
value to be tested- Returns:
true
if the argument is a finite floating-point value,false
otherwise.- Since:
- 1.8
-
isNaN
public boolean isNaN()Returnstrue
if thisDouble
value is a Not-a-Number (NaN),false
otherwise.- Returns:
true
if the value represented by this object is NaN;false
otherwise.
-
isInfinite
public boolean isInfinite()Returnstrue
if thisDouble
value is infinitely large in magnitude,false
otherwise.- Returns:
true
if the value represented by this object is positive infinity or negative infinity;false
otherwise.
-
toString
Returns a string representation of thisDouble
object. The primitivedouble
value represented by this object is converted to a string exactly as if by the methodtoString
of one argument. -
byteValue
public byte byteValue()Returns the value of thisDouble
as abyte
after a narrowing primitive conversion.- Overrides:
byteValue
in classNumber
- Returns:
- the
double
value 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 thisDouble
as ashort
after a narrowing primitive conversion.- Overrides:
shortValue
in classNumber
- Returns:
- the
double
value 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 thisDouble
as anint
after a narrowing primitive conversion.- Specified by:
intValue
in classNumber
- API Note:
- This method corresponds to the convertToIntegerTowardZero operation defined in IEEE 754.
- Returns:
- the
double
value 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 thisDouble
as along
after a narrowing primitive conversion.- Specified by:
longValue
in classNumber
- API Note:
- This method corresponds to the convertToIntegerTowardZero operation defined in IEEE 754.
- Returns:
- the
double
value 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 thisDouble
as afloat
after a narrowing primitive conversion.- Specified by:
floatValue
in classNumber
- API Note:
- This method corresponds to the convertFormat operation defined in IEEE 754.
- Returns:
- the
double
value 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 thedouble
value of thisDouble
object.- Specified by:
doubleValue
in classNumber
- Returns:
- the
double
value represented by this object
-
hashCode
public int hashCode()Returns a hash code for thisDouble
object. The result is the exclusive OR of the two halves of thelong
integer bit representation, exactly as produced by the methoddoubleToLongBits(double)
, of the primitivedouble
value represented by thisDouble
object. That is, the hash code is the value of the expression:(int)(v^(v>>>32))
v
is defined by:long v = Double.doubleToLongBits(this.doubleValue());
-
hashCode
public static int hashCode(double value) Returns a hash code for adouble
value; compatible withDouble.hashCode()
.- Parameters:
value
- the value to hash- Returns:
- a hash code value for a
double
value. - Since:
- 1.8
-
equals
Compares this object against the specified object. The result istrue
if and only if the argument is notnull
and is aDouble
object that represents adouble
that has the same value as thedouble
represented by this object. For this purpose, twodouble
values are considered to be the same if and only if the methoddoubleToLongBits(double)
returns the identicallong
value when applied to each.- Overrides:
equals
in classObject
- API Note:
- This method is defined in terms of
doubleToLongBits(double)
rather than the==
operator ondouble
values 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:
true
if this object is the same as the obj argument;false
otherwise.- 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
long
integer 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
- adouble
precision 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
long
integer representing the actual NaN value. Unlike thedoubleToLongBits
method,doubleToRawLongBits
does not collapse all the bit patterns encoding a NaN to a single "canonical" NaN value.In all cases, the result is a
long
integer that, when given to thelongBitsToDouble(long)
method, will produce a floating-point value the same as the argument todoubleToRawLongBits
.- Parameters:
value
- adouble
precision floating-point number.- Returns:
- the bits that represent the floating-point number.
- Since:
- 1.3
-
longBitsToDouble
public static double longBitsToDouble(long bits) Returns thedouble
value 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
0x7ff0000000000001L
through0x7fffffffffffffffL
or in the range0xfff0000000000001L
through0xffffffffffffffffL
, 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.doubleToRawLongBits
method.In all other cases, let s, e, and m be three values that can be computed from the argument:
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
double
NaN with exactly same bit pattern as thelong
argument. 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. SolongBitsToDouble
may not be able to return adouble
with a signaling NaN bit pattern. Consequently, for somelong
values,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
- anylong
integer.- Returns:
- the
double
floating-point value with the same bit pattern.
-
compareTo
Compares twoDouble
objects numerically. This method imposes a total order onDouble
objects with two differences compared to the incomplete order defined by the Java language numerical comparison operators (<, <=, ==, >=, >
) ondouble
values.- A NaN is unordered with respect to other
values and unequal to itself under the comparison
operators. This method chooses to define
Double.NaN
to be equal to itself and greater than all otherdouble
values (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
).
Double
objects imposed by this method is consistent with equals; see this discussion for details of floating-point comparison and ordering.- Specified by:
compareTo
in interfaceComparable<Double>
- Parameters:
anotherDouble
- theDouble
to be compared.- Returns:
- the value
0
ifanotherDouble
is numerically equal to thisDouble
; a value less than0
if thisDouble
is numerically less thananotherDouble
; and a value greater than0
if thisDouble
is 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 specifieddouble
values. 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 firstdouble
to compared2
- the seconddouble
to compare- Returns:
- the value
0
ifd1
is numerically equal tod2
; a value less than0
ifd1
is numerically less thand2
; and a value greater than0
ifd1
is numerically greater thand2
. - Since:
- 1.4
-
sum
public static double sum(double a, double b) Adds twodouble
values 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
a
andb
- 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 twodouble
values 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
a
andb
- Since:
- 1.8
- See Also:
-
min
public static double min(double a, double b) Returns the smaller of twodouble
values 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
a
andb
. - Since:
- 1.8
- See Also:
-
describeConstable
-
resolveConstantDesc
Resolves this instance as aConstantDesc
, the result of which is the instance itself.- Specified by:
resolveConstantDesc
in interfaceConstantDesc
- Parameters:
lookup
- ignored- Returns:
- the Double instance
- Since:
- 12
-