1 /*
2 * Copyright (c) 1994, 2025, Oracle and/or its affiliates. All rights reserved.
3 * Copyright (c) 2025, Alibaba Group Holding Limited. All Rights Reserved.
4 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
5 *
6 * This code is free software; you can redistribute it and/or modify it
7 * under the terms of the GNU General Public License version 2 only, as
8 * published by the Free Software Foundation. Oracle designates this
9 * particular file as subject to the "Classpath" exception as provided
10 * by Oracle in the LICENSE file that accompanied this code.
11 *
12 * This code is distributed in the hope that it will be useful, but WITHOUT
13 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
14 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
15 * version 2 for more details (a copy is included in the LICENSE file that
16 * accompanied this code).
17 *
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
379 * value returned by {@code Double.longBitsToDouble(0x7ff8000000000000L)}.
380 */
941 * {@link java.util.Locale#ROOT} if locale insensitive.
942 *
943 * @apiNote
944 * This method corresponds to the convertFromDecimalCharacter and
945 * convertFromHexCharacter operations defined in IEEE 754.
946 *
947 * @param s the string to be parsed.
948 * @return a {@code Double} object holding the value
949 * represented by the {@code String} argument.
950 * @throws NumberFormatException if the string does not contain a
951 * parsable number.
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
1047
1048 /**
1049 * The value of the Double.
1050 *
1051 * @serial
1052 */
1053 private final double value;
1054
1055 /**
1056 * Constructs a newly allocated {@code Double} object that
1057 * represents the primitive {@code double} argument.
1058 *
1059 * @param value the value to be represented by the {@code Double}.
1060 *
1061 * @deprecated
1062 * It is rarely appropriate to use this constructor. The static factory
1063 * {@link #valueOf(double)} is generally a better choice, as it is
1064 * likely to yield significantly better space and time performance.
1065 */
1066 @Deprecated(since="9")
1067 public Double(double value) {
1068 this.value = value;
1069 }
1070
1071 /**
1072 * Constructs a newly allocated {@code Double} object that
1073 * represents the floating-point value of type {@code double}
1074 * represented by the string. The string is converted to a
1075 * {@code double} value as if by the {@code valueOf} method.
1076 *
1077 * @param s a string to be converted to a {@code Double}.
1078 * @throws NumberFormatException if the string does not contain a
1079 * parsable number.
1080 *
1081 * @deprecated
1082 * It is rarely appropriate to use this constructor.
1083 * Use {@link #parseDouble(String)} to convert a string to a
1084 * {@code double} primitive, or use {@link #valueOf(String)}
1085 * to convert a string to a {@code Double} object.
1086 */
|
1 /*
2 * Copyright (c) 1994, 2026, Oracle and/or its affiliates. All rights reserved.
3 * Copyright (c) 2025, Alibaba Group Holding Limited. All Rights Reserved.
4 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
5 *
6 * This code is free software; you can redistribute it and/or modify it
7 * under the terms of the GNU General Public License version 2 only, as
8 * published by the Free Software Foundation. Oracle designates this
9 * particular file as subject to the "Classpath" exception as provided
10 * by Oracle in the LICENSE file that accompanied this code.
11 *
12 * This code is distributed in the hope that it will be useful, but WITHOUT
13 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
14 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
15 * version 2 for more details (a copy is included in the LICENSE file that
16 * accompanied this code).
17 *
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.Deserializer;
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 /*value*/ 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
389 * value returned by {@code Double.longBitsToDouble(0x7ff8000000000000L)}.
390 */
951 * {@link java.util.Locale#ROOT} if locale insensitive.
952 *
953 * @apiNote
954 * This method corresponds to the convertFromDecimalCharacter and
955 * convertFromHexCharacter operations defined in IEEE 754.
956 *
957 * @param s the string to be parsed.
958 * @return a {@code Double} object holding the value
959 * represented by the {@code String} argument.
960 * @throws NumberFormatException if the string does not contain a
961 * parsable number.
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 * <div class="preview-block">
972 * <div class="preview-comment">
973 * <p>
974 * - When preview features are NOT enabled, {@code Double} is an identity class.
975 * If a new {@code Double} instance is not required, this
976 * method should generally be used in preference to the
977 * constructor {@link #Double(double)}, as this method is
978 * likely to yield significantly better space and time
979 * performance by caching frequently requested values.
980 * </p>
981 * <p>
982 * - When preview features are enabled, {@code Double} is a {@linkplain Class#isValue value class}.
983 * The {@code valueOf} behavior is the same as invoking the constructor.
984 * </p>
985 * </div>
986 * </div>
987 *
988 * @param d a double value.
989 * @return a {@code Double} instance representing {@code d}.
990 * @since 1.5
991 */
992 @IntrinsicCandidate
993 public static Double valueOf(double d) {
994 return new Double(d);
995 }
996
997 /**
998 * Returns a new {@code double} initialized to the value
999 * represented by the specified {@code String}, as performed
1000 * by the {@code valueOf} method of class
1001 * {@code Double}.
1002 *
1003 * @param s the string to be parsed.
1004 * @return the {@code double} value represented by the string
1005 * argument.
1006 * @throws NullPointerException if the string is null
1068
1069 /**
1070 * The value of the Double.
1071 *
1072 * @serial
1073 */
1074 private final double value;
1075
1076 /**
1077 * Constructs a newly allocated {@code Double} object that
1078 * represents the primitive {@code double} argument.
1079 *
1080 * @param value the value to be represented by the {@code Double}.
1081 *
1082 * @deprecated
1083 * It is rarely appropriate to use this constructor. The static factory
1084 * {@link #valueOf(double)} is generally a better choice, as it is
1085 * likely to yield significantly better space and time performance.
1086 */
1087 @Deprecated(since="9")
1088 @Deserializer("value")
1089 public Double(double value) {
1090 this.value = value;
1091 }
1092
1093 /**
1094 * Constructs a newly allocated {@code Double} object that
1095 * represents the floating-point value of type {@code double}
1096 * represented by the string. The string is converted to a
1097 * {@code double} value as if by the {@code valueOf} method.
1098 *
1099 * @param s a string to be converted to a {@code Double}.
1100 * @throws NumberFormatException if the string does not contain a
1101 * parsable number.
1102 *
1103 * @deprecated
1104 * It is rarely appropriate to use this constructor.
1105 * Use {@link #parseDouble(String)} to convert a string to a
1106 * {@code double} primitive, or use {@link #valueOf(String)}
1107 * to convert a string to a {@code Double} object.
1108 */
|