Module java.base
Package java.lang

# Class Double

≠
public final class Double
extends java.lang.Number
implements java.lang.Comparable<java.lang.Double>, java.lang.constant.Constable, java.lang.constant.ConstantDesc
Comparing jdk-master and valhalla-csr-open

All Implemented Interfaces:
  `Serializable, Comparable<Double>, Constable, ConstantDesc`

public final class Double extends Number implements Comparable<Double>, Constable, ConstantDesc
The `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 mutexes, or with object references.

When preview features are enabled, `Double` is a value classPREVIEW . Use of value class instances for synchronization, mutexes, or with object references result in `IdentityException` PREVIEW Moved out of a paragraph.Moved to a division with class preview-block.Moved to a division with class preview-comment..

## 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` and `v2` are both NaN, then `v1 == v2` has the value `false` . Therefore, for two NaN arguments the reflexive property of an equivalence relation is not satisfied by the `==` operator.
- If `v1` represents `+0.0` while `v2` represents `-0.0` , or vice versa, then `v1 == v2` has the value `true` even though `+0.0` and `-0.0` are distinguishable under various floating-point operations. For example, `1.0/+0.0` evaluates to positive infinity while `1.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` values `a` and `b` is implemented by the expression
  `Double.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.
  Expressions implementing this equivalence relation include:
  - `Double.doubleToLongBits(a) == Double.doubleToLongBits(b)`
  - `Double.valueOf(a).equals(Double.valueOf(b))`
  - `Double.compare(a, b) == 0`
  Note that representation equivalence is often an appropriate notion of equivalence to test the behavior of math libraries.

For two binary floating-point values `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.

These are the closest `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

A floating-point value doesn't "know" whether it was the result of rounding up, or rounding down, or an exact operation; it contains no history of how it was computed. Consequently, the sum of

    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).

or

    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).

should not be expected to be exactly equal to 1.0, but only to be close to 1.0. Consequently, the following code is an infinite loop:

    double d = 0.0;
    while (d != 1.0) { // Surprising infinite loop
      d += 0.1; // Sum never _exactly_ equals 1.0
    }

Instead, use an integer loop count for counted loops:

    double d = 0.0;
    for (int i = 0; i < 10; i++) {
      d += 0.1;
    } // Value of d is equal to Math.nextDown(1.0).

or test against a floating-point limit using ordered comparisons (`<` , `<=` , `>` , `>=` ):

    double d = 0.0;
    while (d <= 1.0) {
      d += 0.1;
    } // Value of d approximately 1.0999999999999999

While floating-point arithmetic may have surprising results, IEEE 754 floating-point arithmetic follows a principled design and its behavior is predictable on the Java platform.

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
  - IEEE Standard for Floating-Point Arithmetic
See Also:
  - Serialized Form

## Fields

- =
  public static final int BYTES = 8
- =
  public static final int MAX_EXPONENT = 1023
- =
  public static final double MAX_VALUE = 1.7976931348623157E308
- =
  public static final int MIN_EXPONENT = -1022
- =
  public static final double MIN_NORMAL = 2.2250738585072014E-308
- =
  public static final double MIN_VALUE = 4.9E-324
- =
  public static final double NEGATIVE_INFINITY = -Infinity
- =
  public static final double NaN = NaN
- =
  public static final double POSITIVE_INFINITY = Infinity
- =
  public static final int PRECISION = 53
- =
  public static final int SIZE = 64
- =
  public static final java.lang.Class<java.lang.Double> TYPE

## Constructors

- =
  @Deprecated(since="9")
  public Double(double arg0)
- =
  @Deprecated(since="9")
  public Double(java.lang.String arg0) throws java.lang.NumberFormatException

## Methods

- =
  public byte byteValue()
- =
  public static int compare(double arg0, double arg1)
- =
  public int compareTo(java.lang.Double arg0)
- =
  public java.util.Optional<java.lang.Double> describeConstable()
- =
  public static long doubleToLongBits(double arg0)
- =
  public static long doubleToRawLongBits(double arg0)
- =
  public double doubleValue()
- =
  public boolean equals(java.lang.Object arg0)
- =
  public float floatValue()
- =
  public int hashCode()
- =
  public static int hashCode(double arg0)
- =
  public int intValue()
- =
  public static boolean isFinite(double arg0)
- =
  public boolean isInfinite()
- =
  public static boolean isInfinite(double arg0)
- =
  public boolean isNaN()
- =
  public static boolean isNaN(double arg0)
- =
  public static double longBitsToDouble(long arg0)
- =
  public long longValue()
- =
  public static double max(double arg0, double arg1)
- =
  public static double min(double arg0, double arg1)
- =
  public static double parseDouble(java.lang.String arg0) throws java.lang.NumberFormatException
- =
  public java.lang.Double resolveConstantDesc(java.lang.invoke.MethodHandles.Lookup arg0)
- =
  public short shortValue()
- =
  public static double sum(double arg0, double arg1)
- =
  public static java.lang.String toHexString(double arg0)
- =
  public java.lang.String toString()
- =
  public static java.lang.String toString(double arg0)
- =
  public static java.lang.Double valueOf(double arg0)
- =
  public static java.lang.Double valueOf(java.lang.String arg0) throws java.lang.NumberFormatException

## Serialized Form

=

### serialVersionUID

=-9172774392245257468

### Serialized Fields

- =
  double value

## Summary

Differences
| Elements | Comments | Descriptions | Total
Added | Changed | Removed | Added | Changed | Removed | Added | Changed | Removed
--- | --- | --- | --- | --- | --- | --- | --- | ---
Double |  |  |  |  |  |  | 7 | 2 |  | 9
Total |  |  |  |  |  |  | 7 | 2 |  | 9