1 /*
2 * Copyright (c) 1994, 2025, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
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.FloatConsts;
34 import jdk.internal.math.FloatingDecimal;
35 import jdk.internal.math.FloatToDecimal;
36 import jdk.internal.vm.annotation.IntrinsicCandidate;
37
38 /**
39 * The {@code Float} class is the {@linkplain
40 * java.lang##wrapperClass wrapper class} for values of the primitive
41 * type {@code float}. An object of type {@code Float} contains a
42 * single field whose type is {@code float}.
43 *
44 * <p>In addition, this class provides several methods for converting a
45 * {@code float} to a {@code String} and a
46 * {@code String} to a {@code float}, as well as other
47 * constants and methods useful when dealing with a
48 * {@code float}.
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 * The class {@code java.lang.Double} has a {@linkplain
60 * Double##equivalenceRelation discussion of equality,
61 * equivalence, and comparison of floating-point values} that is
62 * equally applicable to {@code float} values.
63 *
64 * <h2><a id=decimalToBinaryConversion>Decimal ↔ Binary Conversion Issues</a></h2>
65 *
66 * The {@linkplain Double##decimalToBinaryConversion discussion of binary to
67 * decimal conversion issues} in {@code java.lang.Double} is also
68 * applicable to {@code float} values.
69 *
70 * @spec https://standards.ieee.org/ieee/754/6210/
71 * IEEE Standard for Floating-Point Arithmetic
72 *
73 * @since 1.0
74 */
75 @jdk.internal.ValueBased
76 public final class Float extends Number
77 implements Comparable<Float>, Constable, ConstantDesc {
78 /**
79 * A constant holding the positive infinity of type
80 * {@code float}. It is equal to the value returned by
81 * {@code Float.intBitsToFloat(0x7f800000)}.
82 */
83 public static final float POSITIVE_INFINITY = 1.0f / 0.0f;
84
85 /**
86 * A constant holding the negative infinity of type
87 * {@code float}. It is equal to the value returned by
88 * {@code Float.intBitsToFloat(0xff800000)}.
89 */
90 public static final float NEGATIVE_INFINITY = -1.0f / 0.0f;
91
92 /**
93 * A constant holding a Not-a-Number (NaN) value of type {@code float}.
94 * It is {@linkplain Double##equivalenceRelation equivalent}
544 * {@link java.util.Locale#ROOT} if locale insensitive.
545 *
546 * @apiNote
547 * This method corresponds to the convertFromDecimalCharacter and
548 * convertFromHexCharacter operations defined in IEEE 754.
549 *
550 * @param s the string to be parsed.
551 * @return a {@code Float} object holding the value
552 * represented by the {@code String} argument.
553 * @throws NumberFormatException if the string does not contain a
554 * parsable number.
555 * @see Double##decimalToBinaryConversion Decimal ↔ Binary Conversion Issues
556 */
557 public static Float valueOf(String s) throws NumberFormatException {
558 return new Float(parseFloat(s));
559 }
560
561 /**
562 * Returns a {@code Float} instance representing the specified
563 * {@code float} value.
564 * If a new {@code Float} instance is not required, this method
565 * should generally be used in preference to the constructor
566 * {@link #Float(float)}, as this method is likely to yield
567 * significantly better space and time performance by caching
568 * frequently requested values.
569 *
570 * @param f a float value.
571 * @return a {@code Float} instance representing {@code f}.
572 * @since 1.5
573 */
574 @IntrinsicCandidate
575 public static Float valueOf(float f) {
576 return new Float(f);
577 }
578
579 /**
580 * Returns a new {@code float} initialized to the value
581 * represented by the specified {@code String}, as performed
582 * by the {@code valueOf} method of class {@code Float}.
583 *
584 * @param s the string to be parsed.
585 * @return the {@code float} value represented by the string
586 * argument.
587 * @throws NullPointerException if the string is null
588 * @throws NumberFormatException if the string does not contain a
650
651 /**
652 * The value of the Float.
653 *
654 * @serial
655 */
656 private final float value;
657
658 /**
659 * Constructs a newly allocated {@code Float} object that
660 * represents the primitive {@code float} argument.
661 *
662 * @param value the value to be represented by the {@code Float}.
663 *
664 * @deprecated
665 * It is rarely appropriate to use this constructor. The static factory
666 * {@link #valueOf(float)} is generally a better choice, as it is
667 * likely to yield significantly better space and time performance.
668 */
669 @Deprecated(since="9")
670 public Float(float value) {
671 this.value = value;
672 }
673
674 /**
675 * Constructs a newly allocated {@code Float} object that
676 * represents the argument converted to type {@code float}.
677 *
678 * @param value the value to be represented by the {@code Float}.
679 *
680 * @deprecated
681 * It is rarely appropriate to use this constructor. Instead, use the
682 * static factory method {@link #valueOf(float)} method as follows:
683 * {@code Float.valueOf((float)value)}.
684 */
685 @Deprecated(since="9")
686 public Float(double value) {
687 this.value = (float)value;
688 }
689
|
1 /*
2 * Copyright (c) 1994, 2026, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
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.FloatConsts;
34 import jdk.internal.math.FloatingDecimal;
35 import jdk.internal.math.FloatToDecimal;
36 import jdk.internal.value.DeserializeConstructor;
37 import jdk.internal.vm.annotation.IntrinsicCandidate;
38
39 /**
40 * The {@code Float} class is the {@linkplain
41 * java.lang##wrapperClass wrapper class} for values of the primitive
42 * type {@code float}. An object of type {@code Float} contains a
43 * single field whose type is {@code float}.
44 *
45 * <p>In addition, this class provides several methods for converting a
46 * {@code float} to a {@code String} and a
47 * {@code String} to a {@code float}, as well as other
48 * constants and methods useful when dealing with a
49 * {@code float}.
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 Float} 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 * The class {@code java.lang.Double} has a {@linkplain
69 * Double##equivalenceRelation discussion of equality,
70 * equivalence, and comparison of floating-point values} that is
71 * equally applicable to {@code float} values.
72 *
73 * <h2><a id=decimalToBinaryConversion>Decimal ↔ Binary Conversion Issues</a></h2>
74 *
75 * The {@linkplain Double##decimalToBinaryConversion discussion of binary to
76 * decimal conversion issues} in {@code java.lang.Double} is also
77 * applicable to {@code float} values.
78 *
79 * @spec https://standards.ieee.org/ieee/754/6210/
80 * IEEE Standard for Floating-Point Arithmetic
81 *
82 * @since 1.0
83 */
84 @jdk.internal.MigratedValueClass
85 @jdk.internal.ValueBased
86 public final class Float extends Number
87 implements Comparable<Float>, Constable, ConstantDesc {
88 /**
89 * A constant holding the positive infinity of type
90 * {@code float}. It is equal to the value returned by
91 * {@code Float.intBitsToFloat(0x7f800000)}.
92 */
93 public static final float POSITIVE_INFINITY = 1.0f / 0.0f;
94
95 /**
96 * A constant holding the negative infinity of type
97 * {@code float}. It is equal to the value returned by
98 * {@code Float.intBitsToFloat(0xff800000)}.
99 */
100 public static final float NEGATIVE_INFINITY = -1.0f / 0.0f;
101
102 /**
103 * A constant holding a Not-a-Number (NaN) value of type {@code float}.
104 * It is {@linkplain Double##equivalenceRelation equivalent}
554 * {@link java.util.Locale#ROOT} if locale insensitive.
555 *
556 * @apiNote
557 * This method corresponds to the convertFromDecimalCharacter and
558 * convertFromHexCharacter operations defined in IEEE 754.
559 *
560 * @param s the string to be parsed.
561 * @return a {@code Float} object holding the value
562 * represented by the {@code String} argument.
563 * @throws NumberFormatException if the string does not contain a
564 * parsable number.
565 * @see Double##decimalToBinaryConversion Decimal ↔ Binary Conversion Issues
566 */
567 public static Float valueOf(String s) throws NumberFormatException {
568 return new Float(parseFloat(s));
569 }
570
571 /**
572 * Returns a {@code Float} instance representing the specified
573 * {@code float} value.
574 * <div class="preview-block">
575 * <div class="preview-comment">
576 * <p>
577 * - When preview features are NOT enabled, {@code Float} is an identity class.
578 * If a new {@code Float} instance is not required, this
579 * method should generally be used in preference to the
580 * constructor {@link #Float(float)}, as this method is
581 * likely to yield significantly better space and time
582 * performance by caching frequently requested values.
583 * </p>
584 * <p>
585 * - When preview features are enabled, {@code Float} is a {@linkplain Class#isValue value class}.
586 * The {@code valueOf} behavior is the same as invoking the constructor.
587 * </p>
588 * </div>
589 * </div>
590 *
591 * @param f a float value.
592 * @return a {@code Float} instance representing {@code f}.
593 * @since 1.5
594 */
595 @IntrinsicCandidate
596 public static Float valueOf(float f) {
597 return new Float(f);
598 }
599
600 /**
601 * Returns a new {@code float} initialized to the value
602 * represented by the specified {@code String}, as performed
603 * by the {@code valueOf} method of class {@code Float}.
604 *
605 * @param s the string to be parsed.
606 * @return the {@code float} value represented by the string
607 * argument.
608 * @throws NullPointerException if the string is null
609 * @throws NumberFormatException if the string does not contain a
671
672 /**
673 * The value of the Float.
674 *
675 * @serial
676 */
677 private final float value;
678
679 /**
680 * Constructs a newly allocated {@code Float} object that
681 * represents the primitive {@code float} argument.
682 *
683 * @param value the value to be represented by the {@code Float}.
684 *
685 * @deprecated
686 * It is rarely appropriate to use this constructor. The static factory
687 * {@link #valueOf(float)} is generally a better choice, as it is
688 * likely to yield significantly better space and time performance.
689 */
690 @Deprecated(since="9")
691 @DeserializeConstructor
692 public Float(float value) {
693 this.value = value;
694 }
695
696 /**
697 * Constructs a newly allocated {@code Float} object that
698 * represents the argument converted to type {@code float}.
699 *
700 * @param value the value to be represented by the {@code Float}.
701 *
702 * @deprecated
703 * It is rarely appropriate to use this constructor. Instead, use the
704 * static factory method {@link #valueOf(float)} method as follows:
705 * {@code Float.valueOf((float)value)}.
706 */
707 @Deprecated(since="9")
708 public Float(double value) {
709 this.value = (float)value;
710 }
711
|