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