18 * You should have received a copy of the GNU General Public License version
19 * 2 along with this work; if not, write to the Free Software Foundation,
20 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
21 *
22 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
23 * or visit www.oracle.com if you need additional information or have any
24 * questions.
25 */
26
27 package java.lang;
28
29 import java.lang.invoke.MethodHandles;
30 import java.lang.constant.Constable;
31 import java.lang.constant.ConstantDesc;
32 import java.util.Optional;
33
34 import jdk.internal.math.FloatingDecimal;
35 import jdk.internal.math.DoubleConsts;
36 import jdk.internal.math.DoubleToDecimal;
37 import jdk.internal.util.DecimalDigits;
38 import jdk.internal.vm.annotation.IntrinsicCandidate;
39
40 /**
41 * The {@code Double} class is the {@linkplain
42 * java.lang##wrapperClass wrapper class} for values of the primitive
43 * type {@code double}. An object of type {@code Double} contains a
44 * single field whose type is {@code double}.
45 *
46 * <p>In addition, this class provides several methods for converting a
47 * {@code double} to a {@code String} and a
48 * {@code String} to a {@code double}, as well as other
49 * constants and methods useful when dealing with a
50 * {@code double}.
51 *
52 * <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
53 * class; programmers should treat instances that are
54 * {@linkplain #equals(Object) equal} as interchangeable and should not
55 * use instances for synchronization, or unpredictable behavior may
56 * occur. For example, in a future release, synchronization may fail.
57 *
58 * <h2><a id=equivalenceRelation>Floating-point Equality, Equivalence,
59 * and Comparison</a></h2>
60 *
61 * IEEE 754 floating-point values include finite nonzero values,
62 * signed zeros ({@code +0.0} and {@code -0.0}), signed infinities
63 * ({@linkplain Double#POSITIVE_INFINITY positive infinity} and
64 * {@linkplain Double#NEGATIVE_INFINITY negative infinity}), and
65 * {@linkplain Double#NaN NaN} (not-a-number).
66 *
67 * <p>An <em>equivalence relation</em> on a set of values is a boolean
68 * relation on pairs of values that is reflexive, symmetric, and
69 * transitive. For more discussion of equivalence relations and object
70 * equality, see the {@link Object#equals Object.equals}
71 * specification. An equivalence relation partitions the values it
72 * operates over into sets called <i>equivalence classes</i>. All the
73 * members of the equivalence class are equal to each other under the
74 * relation. An equivalence class may contain only a single member. At
75 * least for some purposes, all the members of an equivalence class
76 * are substitutable for each other. In particular, in a numeric
339 * double d = 0.0;
340 * while (d <= 1.0) {
341 * d += 0.1;
342 * } // Value of d approximately 1.0999999999999999
343 * }
344 *
345 * While floating-point arithmetic may have surprising results, IEEE
346 * 754 floating-point arithmetic follows a principled design and its
347 * behavior is predictable on the Java platform.
348 *
349 * @jls 4.2.3 Floating-Point Types and Values
350 * @jls 4.2.4 Floating-Point Operations
351 * @jls 15.21.1 Numerical Equality Operators == and !=
352 * @jls 15.20.1 Numerical Comparison Operators {@code <}, {@code <=}, {@code >}, and {@code >=}
353 *
354 * @spec https://standards.ieee.org/ieee/754/6210/
355 * IEEE Standard for Floating-Point Arithmetic
356 *
357 * @since 1.0
358 */
359 @jdk.internal.ValueBased
360 public final class Double extends Number
361 implements Comparable<Double>, Constable, ConstantDesc {
362 /**
363 * A constant holding the positive infinity of type
364 * {@code double}. It is equal to the value returned by
365 * {@code Double.longBitsToDouble(0x7ff0000000000000L)}.
366 */
367 public static final double POSITIVE_INFINITY = 1.0 / 0.0;
368
369 /**
370 * A constant holding the negative infinity of type
371 * {@code double}. It is equal to the value returned by
372 * {@code Double.longBitsToDouble(0xfff0000000000000L)}.
373 */
374 public static final double NEGATIVE_INFINITY = -1.0 / 0.0;
375
376 /**
377 * A constant holding a Not-a-Number (NaN) value of type {@code double}.
378 * It is {@linkplain Double##equivalenceRelation equivalent} to the
952 * @see Double##decimalToBinaryConversion Decimal ↔ Binary Conversion Issues
953 */
954 public static Double valueOf(String s) throws NumberFormatException {
955 return new Double(parseDouble(s));
956 }
957
958 /**
959 * Returns a {@code Double} instance representing the specified
960 * {@code double} value.
961 * If a new {@code Double} instance is not required, this method
962 * should generally be used in preference to the constructor
963 * {@link #Double(double)}, as this method is likely to yield
964 * significantly better space and time performance by caching
965 * frequently requested values.
966 *
967 * @param d a double value.
968 * @return a {@code Double} instance representing {@code d}.
969 * @since 1.5
970 */
971 @IntrinsicCandidate
972 public static Double valueOf(double d) {
973 return new Double(d);
974 }
975
976 /**
977 * Returns a new {@code double} initialized to the value
978 * represented by the specified {@code String}, as performed
979 * by the {@code valueOf} method of class
980 * {@code Double}.
981 *
982 * @param s the string to be parsed.
983 * @return the {@code double} value represented by the string
984 * argument.
985 * @throws NullPointerException if the string is null
986 * @throws NumberFormatException if the string does not contain
987 * a parsable {@code double}.
988 * @see java.lang.Double#valueOf(String)
989 * @see Double##decimalToBinaryConversion Decimal ↔ Binary Conversion Issues
990 * @since 1.2
991 */
|
18 * You should have received a copy of the GNU General Public License version
19 * 2 along with this work; if not, write to the Free Software Foundation,
20 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
21 *
22 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
23 * or visit www.oracle.com if you need additional information or have any
24 * questions.
25 */
26
27 package java.lang;
28
29 import java.lang.invoke.MethodHandles;
30 import java.lang.constant.Constable;
31 import java.lang.constant.ConstantDesc;
32 import java.util.Optional;
33
34 import jdk.internal.math.FloatingDecimal;
35 import jdk.internal.math.DoubleConsts;
36 import jdk.internal.math.DoubleToDecimal;
37 import jdk.internal.util.DecimalDigits;
38 import jdk.internal.value.DeserializeConstructor;
39 import jdk.internal.vm.annotation.IntrinsicCandidate;
40
41 /**
42 * The {@code Double} class is the {@linkplain
43 * java.lang##wrapperClass wrapper class} for values of the primitive
44 * type {@code double}. An object of type {@code Double} contains a
45 * single field whose type is {@code double}.
46 *
47 * <p>In addition, this class provides several methods for converting a
48 * {@code double} to a {@code String} and a
49 * {@code String} to a {@code double}, as well as other
50 * constants and methods useful when dealing with a
51 * {@code double}.
52 *
53 * <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
54 * class; programmers should treat instances that are {@linkplain #equals(Object) equal}
55 * as interchangeable and should not use instances for synchronization, mutexes, or
56 * with {@linkplain java.lang.ref.Reference object references}.
57 *
58 * <div class="preview-block">
59 * <div class="preview-comment">
60 * When preview features are enabled, {@code Double} is a {@linkplain Class#isValue value class}.
61 * Use of value class instances for synchronization, mutexes, or with
62 * {@linkplain java.lang.ref.Reference object references} result in
63 * {@link IdentityException}.
64 * </div>
65 * </div>
66 *
67 * <h2><a id=equivalenceRelation>Floating-point Equality, Equivalence,
68 * and Comparison</a></h2>
69 *
70 * IEEE 754 floating-point values include finite nonzero values,
71 * signed zeros ({@code +0.0} and {@code -0.0}), signed infinities
72 * ({@linkplain Double#POSITIVE_INFINITY positive infinity} and
73 * {@linkplain Double#NEGATIVE_INFINITY negative infinity}), and
74 * {@linkplain Double#NaN NaN} (not-a-number).
75 *
76 * <p>An <em>equivalence relation</em> on a set of values is a boolean
77 * relation on pairs of values that is reflexive, symmetric, and
78 * transitive. For more discussion of equivalence relations and object
79 * equality, see the {@link Object#equals Object.equals}
80 * specification. An equivalence relation partitions the values it
81 * operates over into sets called <i>equivalence classes</i>. All the
82 * members of the equivalence class are equal to each other under the
83 * relation. An equivalence class may contain only a single member. At
84 * least for some purposes, all the members of an equivalence class
85 * are substitutable for each other. In particular, in a numeric
348 * double d = 0.0;
349 * while (d <= 1.0) {
350 * d += 0.1;
351 * } // Value of d approximately 1.0999999999999999
352 * }
353 *
354 * While floating-point arithmetic may have surprising results, IEEE
355 * 754 floating-point arithmetic follows a principled design and its
356 * behavior is predictable on the Java platform.
357 *
358 * @jls 4.2.3 Floating-Point Types and Values
359 * @jls 4.2.4 Floating-Point Operations
360 * @jls 15.21.1 Numerical Equality Operators == and !=
361 * @jls 15.20.1 Numerical Comparison Operators {@code <}, {@code <=}, {@code >}, and {@code >=}
362 *
363 * @spec https://standards.ieee.org/ieee/754/6210/
364 * IEEE Standard for Floating-Point Arithmetic
365 *
366 * @since 1.0
367 */
368 @jdk.internal.MigratedValueClass
369 @jdk.internal.ValueBased
370 public final class Double extends Number
371 implements Comparable<Double>, Constable, ConstantDesc {
372 /**
373 * A constant holding the positive infinity of type
374 * {@code double}. It is equal to the value returned by
375 * {@code Double.longBitsToDouble(0x7ff0000000000000L)}.
376 */
377 public static final double POSITIVE_INFINITY = 1.0 / 0.0;
378
379 /**
380 * A constant holding the negative infinity of type
381 * {@code double}. It is equal to the value returned by
382 * {@code Double.longBitsToDouble(0xfff0000000000000L)}.
383 */
384 public static final double NEGATIVE_INFINITY = -1.0 / 0.0;
385
386 /**
387 * A constant holding a Not-a-Number (NaN) value of type {@code double}.
388 * It is {@linkplain Double##equivalenceRelation equivalent} to the
962 * @see Double##decimalToBinaryConversion Decimal ↔ Binary Conversion Issues
963 */
964 public static Double valueOf(String s) throws NumberFormatException {
965 return new Double(parseDouble(s));
966 }
967
968 /**
969 * Returns a {@code Double} instance representing the specified
970 * {@code double} value.
971 * If a new {@code Double} instance is not required, this method
972 * should generally be used in preference to the constructor
973 * {@link #Double(double)}, as this method is likely to yield
974 * significantly better space and time performance by caching
975 * frequently requested values.
976 *
977 * @param d a double value.
978 * @return a {@code Double} instance representing {@code d}.
979 * @since 1.5
980 */
981 @IntrinsicCandidate
982 @DeserializeConstructor
983 public static Double valueOf(double d) {
984 return new Double(d);
985 }
986
987 /**
988 * Returns a new {@code double} initialized to the value
989 * represented by the specified {@code String}, as performed
990 * by the {@code valueOf} method of class
991 * {@code Double}.
992 *
993 * @param s the string to be parsed.
994 * @return the {@code double} value represented by the string
995 * argument.
996 * @throws NullPointerException if the string is null
997 * @throws NumberFormatException if the string does not contain
998 * a parsable {@code double}.
999 * @see java.lang.Double#valueOf(String)
1000 * @see Double##decimalToBinaryConversion Decimal ↔ Binary Conversion Issues
1001 * @since 1.2
1002 */
|