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 sun.misc.FloatingDecimal;
29 import sun.misc.FloatConsts;
30 import sun.misc.DoubleConsts;
31
32 /**
33 * The {@code Float} class wraps a value of primitive type
34 * {@code float} in an object. An object of type
35 * {@code Float} contains a single field whose type is
36 * {@code float}.
37 *
38 * <p>In addition, this class provides several methods for converting a
39 * {@code float} to a {@code String} and a
40 * {@code String} to a {@code float}, as well as other
41 * constants and methods useful when dealing with a
42 * {@code float}.
43 *
44 * @author Lee Boynton
45 * @author Arthur van Hoff
46 * @author Joseph D. Darcy
47 * @since 1.0
48 */
49 public final class Float extends Number implements Comparable<Float> {
50 /**
412 * @throws NumberFormatException if the string does not contain a
413 * parsable number.
414 */
415 public static Float valueOf(String s) throws NumberFormatException {
416 return new Float(parseFloat(s));
417 }
418
419 /**
420 * Returns a {@code Float} instance representing the specified
421 * {@code float} value.
422 * If a new {@code Float} instance is not required, this method
423 * should generally be used in preference to the constructor
424 * {@link #Float(float)}, as this method is likely to yield
425 * significantly better space and time performance by caching
426 * frequently requested values.
427 *
428 * @param f a float value.
429 * @return a {@code Float} instance representing {@code f}.
430 * @since 1.5
431 */
432 public static Float valueOf(float f) {
433 return new Float(f);
434 }
435
436 /**
437 * Returns a new {@code float} initialized to the value
438 * represented by the specified {@code String}, as performed
439 * by the {@code valueOf} method of class {@code Float}.
440 *
441 * @param s the string to be parsed.
442 * @return the {@code float} value represented by the string
443 * argument.
444 * @throws NullPointerException if the string is null
445 * @throws NumberFormatException if the string does not contain a
446 * parsable {@code float}.
447 * @see java.lang.Float#valueOf(String)
448 * @since 1.2
449 */
450 public static float parseFloat(String s) throws NumberFormatException {
451 return FloatingDecimal.parseFloat(s);
605 return (int)value;
606 }
607
608 /**
609 * Returns value of this {@code Float} as a {@code long} after a
610 * narrowing primitive conversion.
611 *
612 * @return the {@code float} value represented by this object
613 * converted to type {@code long}
614 * @jls 5.1.3 Narrowing Primitive Conversions
615 */
616 public long longValue() {
617 return (long)value;
618 }
619
620 /**
621 * Returns the {@code float} value of this {@code Float} object.
622 *
623 * @return the {@code float} value represented by this object
624 */
625 public float floatValue() {
626 return value;
627 }
628
629 /**
630 * Returns the value of this {@code Float} as a {@code double}
631 * after a widening primitive conversion.
632 *
633 * @return the {@code float} value represented by this
634 * object converted to type {@code double}
635 * @jls 5.1.2 Widening Primitive Conversions
636 */
637 public double doubleValue() {
638 return (double)value;
639 }
640
641 /**
642 * Returns a hash code for this {@code Float} object. The
643 * result is the integer bit representation, exactly as produced
644 * by the method {@link #floatToIntBits(float)}, of the primitive
723 * {@code 0x007fffff}) represent the significand (sometimes called
724 * the mantissa) of the floating-point number.
725 *
726 * <p>If the argument is positive infinity, the result is
727 * {@code 0x7f800000}.
728 *
729 * <p>If the argument is negative infinity, the result is
730 * {@code 0xff800000}.
731 *
732 * <p>If the argument is NaN, the result is {@code 0x7fc00000}.
733 *
734 * <p>In all cases, the result is an integer that, when given to the
735 * {@link #intBitsToFloat(int)} method, will produce a floating-point
736 * value the same as the argument to {@code floatToIntBits}
737 * (except all NaN values are collapsed to a single
738 * "canonical" NaN value).
739 *
740 * @param value a floating-point number.
741 * @return the bits that represent the floating-point number.
742 */
743 public static int floatToIntBits(float value) {
744 if (!isNaN(value)) {
745 return floatToRawIntBits(value);
746 }
747 return 0x7fc00000;
748 }
749
750 /**
751 * Returns a representation of the specified floating-point value
752 * according to the IEEE 754 floating-point "single format" bit
753 * layout, preserving Not-a-Number (NaN) values.
754 *
755 * <p>Bit 31 (the bit that is selected by the mask
756 * {@code 0x80000000}) represents the sign of the floating-point
757 * number.
758 * Bits 30-23 (the bits that are selected by the mask
759 * {@code 0x7f800000}) represent the exponent.
760 * Bits 22-0 (the bits that are selected by the mask
761 * {@code 0x007fffff}) represent the significand (sometimes called
762 * the mantissa) of the floating-point number.
765 * {@code 0x7f800000}.
766 *
767 * <p>If the argument is negative infinity, the result is
768 * {@code 0xff800000}.
769 *
770 * <p>If the argument is NaN, the result is the integer representing
771 * the actual NaN value. Unlike the {@code floatToIntBits}
772 * method, {@code floatToRawIntBits} does not collapse all the
773 * bit patterns encoding a NaN to a single "canonical"
774 * NaN value.
775 *
776 * <p>In all cases, the result is an integer that, when given to the
777 * {@link #intBitsToFloat(int)} method, will produce a
778 * floating-point value the same as the argument to
779 * {@code floatToRawIntBits}.
780 *
781 * @param value a floating-point number.
782 * @return the bits that represent the floating-point number.
783 * @since 1.3
784 */
785 public static native int floatToRawIntBits(float value);
786
787 /**
788 * Returns the {@code float} value corresponding to a given
789 * bit representation.
790 * The argument is considered to be a representation of a
791 * floating-point value according to the IEEE 754 floating-point
792 * "single format" bit layout.
793 *
794 * <p>If the argument is {@code 0x7f800000}, the result is positive
795 * infinity.
796 *
797 * <p>If the argument is {@code 0xff800000}, the result is negative
798 * infinity.
799 *
800 * <p>If the argument is any value in the range
801 * {@code 0x7f800001} through {@code 0x7fffffff} or in
802 * the range {@code 0xff800001} through
803 * {@code 0xffffffff}, the result is a NaN. No IEEE 754
804 * floating-point operation provided by Java can distinguish
826 * kinds of NaNs, quiet NaNs and <i>signaling NaNs</i>. The
827 * differences between the two kinds of NaN are generally not
828 * visible in Java. Arithmetic operations on signaling NaNs turn
829 * them into quiet NaNs with a different, but often similar, bit
830 * pattern. However, on some processors merely copying a
831 * signaling NaN also performs that conversion. In particular,
832 * copying a signaling NaN to return it to the calling method may
833 * perform this conversion. So {@code intBitsToFloat} may
834 * not be able to return a {@code float} with a signaling NaN
835 * bit pattern. Consequently, for some {@code int} values,
836 * {@code floatToRawIntBits(intBitsToFloat(start))} may
837 * <i>not</i> equal {@code start}. Moreover, which
838 * particular bit patterns represent signaling NaNs is platform
839 * dependent; although all NaN bit patterns, quiet or signaling,
840 * must be in the NaN range identified above.
841 *
842 * @param bits an integer.
843 * @return the {@code float} floating-point value with the same bit
844 * pattern.
845 */
846 public static native float intBitsToFloat(int bits);
847
848 /**
849 * Compares two {@code Float} objects numerically. There are
850 * two ways in which comparisons performed by this method differ
851 * from those performed by the Java language numerical comparison
852 * operators ({@code <, <=, ==, >=, >}) when
853 * applied to primitive {@code float} values:
854 *
855 * <ul><li>
856 * {@code Float.NaN} is considered by this method to
857 * be equal to itself and greater than all other
858 * {@code float} values
859 * (including {@code Float.POSITIVE_INFINITY}).
860 * <li>
861 * {@code 0.0f} is considered by this method to be greater
862 * than {@code -0.0f}.
863 * </ul>
864 *
865 * This ensures that the <i>natural ordering</i> of {@code Float}
|
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 sun.misc.FloatingDecimal;
29 import sun.misc.FloatConsts;
30 import sun.misc.DoubleConsts;
31 import jdk.internal.HotSpotIntrinsicCandidate;
32
33 /**
34 * The {@code Float} class wraps a value of primitive type
35 * {@code float} in an object. An object of type
36 * {@code Float} contains a single field whose type is
37 * {@code float}.
38 *
39 * <p>In addition, this class provides several methods for converting a
40 * {@code float} to a {@code String} and a
41 * {@code String} to a {@code float}, as well as other
42 * constants and methods useful when dealing with a
43 * {@code float}.
44 *
45 * @author Lee Boynton
46 * @author Arthur van Hoff
47 * @author Joseph D. Darcy
48 * @since 1.0
49 */
50 public final class Float extends Number implements Comparable<Float> {
51 /**
413 * @throws NumberFormatException if the string does not contain a
414 * parsable number.
415 */
416 public static Float valueOf(String s) throws NumberFormatException {
417 return new Float(parseFloat(s));
418 }
419
420 /**
421 * Returns a {@code Float} instance representing the specified
422 * {@code float} value.
423 * If a new {@code Float} instance is not required, this method
424 * should generally be used in preference to the constructor
425 * {@link #Float(float)}, as this method is likely to yield
426 * significantly better space and time performance by caching
427 * frequently requested values.
428 *
429 * @param f a float value.
430 * @return a {@code Float} instance representing {@code f}.
431 * @since 1.5
432 */
433 @HotSpotIntrinsicCandidate
434 public static Float valueOf(float f) {
435 return new Float(f);
436 }
437
438 /**
439 * Returns a new {@code float} initialized to the value
440 * represented by the specified {@code String}, as performed
441 * by the {@code valueOf} method of class {@code Float}.
442 *
443 * @param s the string to be parsed.
444 * @return the {@code float} value represented by the string
445 * argument.
446 * @throws NullPointerException if the string is null
447 * @throws NumberFormatException if the string does not contain a
448 * parsable {@code float}.
449 * @see java.lang.Float#valueOf(String)
450 * @since 1.2
451 */
452 public static float parseFloat(String s) throws NumberFormatException {
453 return FloatingDecimal.parseFloat(s);
607 return (int)value;
608 }
609
610 /**
611 * Returns value of this {@code Float} as a {@code long} after a
612 * narrowing primitive conversion.
613 *
614 * @return the {@code float} value represented by this object
615 * converted to type {@code long}
616 * @jls 5.1.3 Narrowing Primitive Conversions
617 */
618 public long longValue() {
619 return (long)value;
620 }
621
622 /**
623 * Returns the {@code float} value of this {@code Float} object.
624 *
625 * @return the {@code float} value represented by this object
626 */
627 @HotSpotIntrinsicCandidate
628 public float floatValue() {
629 return value;
630 }
631
632 /**
633 * Returns the value of this {@code Float} as a {@code double}
634 * after a widening primitive conversion.
635 *
636 * @return the {@code float} value represented by this
637 * object converted to type {@code double}
638 * @jls 5.1.2 Widening Primitive Conversions
639 */
640 public double doubleValue() {
641 return (double)value;
642 }
643
644 /**
645 * Returns a hash code for this {@code Float} object. The
646 * result is the integer bit representation, exactly as produced
647 * by the method {@link #floatToIntBits(float)}, of the primitive
726 * {@code 0x007fffff}) represent the significand (sometimes called
727 * the mantissa) of the floating-point number.
728 *
729 * <p>If the argument is positive infinity, the result is
730 * {@code 0x7f800000}.
731 *
732 * <p>If the argument is negative infinity, the result is
733 * {@code 0xff800000}.
734 *
735 * <p>If the argument is NaN, the result is {@code 0x7fc00000}.
736 *
737 * <p>In all cases, the result is an integer that, when given to the
738 * {@link #intBitsToFloat(int)} method, will produce a floating-point
739 * value the same as the argument to {@code floatToIntBits}
740 * (except all NaN values are collapsed to a single
741 * "canonical" NaN value).
742 *
743 * @param value a floating-point number.
744 * @return the bits that represent the floating-point number.
745 */
746 @HotSpotIntrinsicCandidate
747 public static int floatToIntBits(float value) {
748 if (!isNaN(value)) {
749 return floatToRawIntBits(value);
750 }
751 return 0x7fc00000;
752 }
753
754 /**
755 * Returns a representation of the specified floating-point value
756 * according to the IEEE 754 floating-point "single format" bit
757 * layout, preserving Not-a-Number (NaN) values.
758 *
759 * <p>Bit 31 (the bit that is selected by the mask
760 * {@code 0x80000000}) represents the sign of the floating-point
761 * number.
762 * Bits 30-23 (the bits that are selected by the mask
763 * {@code 0x7f800000}) represent the exponent.
764 * Bits 22-0 (the bits that are selected by the mask
765 * {@code 0x007fffff}) represent the significand (sometimes called
766 * the mantissa) of the floating-point number.
769 * {@code 0x7f800000}.
770 *
771 * <p>If the argument is negative infinity, the result is
772 * {@code 0xff800000}.
773 *
774 * <p>If the argument is NaN, the result is the integer representing
775 * the actual NaN value. Unlike the {@code floatToIntBits}
776 * method, {@code floatToRawIntBits} does not collapse all the
777 * bit patterns encoding a NaN to a single "canonical"
778 * NaN value.
779 *
780 * <p>In all cases, the result is an integer that, when given to the
781 * {@link #intBitsToFloat(int)} method, will produce a
782 * floating-point value the same as the argument to
783 * {@code floatToRawIntBits}.
784 *
785 * @param value a floating-point number.
786 * @return the bits that represent the floating-point number.
787 * @since 1.3
788 */
789 @HotSpotIntrinsicCandidate
790 public static native int floatToRawIntBits(float value);
791
792 /**
793 * Returns the {@code float} value corresponding to a given
794 * bit representation.
795 * The argument is considered to be a representation of a
796 * floating-point value according to the IEEE 754 floating-point
797 * "single format" bit layout.
798 *
799 * <p>If the argument is {@code 0x7f800000}, the result is positive
800 * infinity.
801 *
802 * <p>If the argument is {@code 0xff800000}, the result is negative
803 * infinity.
804 *
805 * <p>If the argument is any value in the range
806 * {@code 0x7f800001} through {@code 0x7fffffff} or in
807 * the range {@code 0xff800001} through
808 * {@code 0xffffffff}, the result is a NaN. No IEEE 754
809 * floating-point operation provided by Java can distinguish
831 * kinds of NaNs, quiet NaNs and <i>signaling NaNs</i>. The
832 * differences between the two kinds of NaN are generally not
833 * visible in Java. Arithmetic operations on signaling NaNs turn
834 * them into quiet NaNs with a different, but often similar, bit
835 * pattern. However, on some processors merely copying a
836 * signaling NaN also performs that conversion. In particular,
837 * copying a signaling NaN to return it to the calling method may
838 * perform this conversion. So {@code intBitsToFloat} may
839 * not be able to return a {@code float} with a signaling NaN
840 * bit pattern. Consequently, for some {@code int} values,
841 * {@code floatToRawIntBits(intBitsToFloat(start))} may
842 * <i>not</i> equal {@code start}. Moreover, which
843 * particular bit patterns represent signaling NaNs is platform
844 * dependent; although all NaN bit patterns, quiet or signaling,
845 * must be in the NaN range identified above.
846 *
847 * @param bits an integer.
848 * @return the {@code float} floating-point value with the same bit
849 * pattern.
850 */
851 @HotSpotIntrinsicCandidate
852 public static native float intBitsToFloat(int bits);
853
854 /**
855 * Compares two {@code Float} objects numerically. There are
856 * two ways in which comparisons performed by this method differ
857 * from those performed by the Java language numerical comparison
858 * operators ({@code <, <=, ==, >=, >}) when
859 * applied to primitive {@code float} values:
860 *
861 * <ul><li>
862 * {@code Float.NaN} is considered by this method to
863 * be equal to itself and greater than all other
864 * {@code float} values
865 * (including {@code Float.POSITIVE_INFINITY}).
866 * <li>
867 * {@code 0.0f} is considered by this method to be greater
868 * than {@code -0.0f}.
869 * </ul>
870 *
871 * This ensures that the <i>natural ordering</i> of {@code Float}
|