1 /*
   2  * Copyright 1994-2006 Sun Microsystems, Inc.  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.  Sun designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
  22  * CA 95054 USA or visit www.sun.com if you need additional information or
  23  * have any questions.
  24  */
  25 
  26 package java.lang;
  27 
  28 import sun.misc.FloatingDecimal;
  29 import sun.misc.FpUtils;
  30 import sun.misc.FloatConsts;
  31 import sun.misc.DoubleConsts;
  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 JDK1.0
  49  */
  50 public final class Float extends Number implements Comparable<Float> {
  51     /**
  52      * A constant holding the positive infinity of type
  53      * {@code float}. It is equal to the value returned by
  54      * {@code Float.intBitsToFloat(0x7f800000)}.
  55      */
  56     public static final float POSITIVE_INFINITY = 1.0f / 0.0f;
  57 
  58     /**
  59      * A constant holding the negative infinity of type
  60      * {@code float}. It is equal to the value returned by
  61      * {@code Float.intBitsToFloat(0xff800000)}.
  62      */
  63     public static final float NEGATIVE_INFINITY = -1.0f / 0.0f;
  64 
  65     /**
  66      * A constant holding a Not-a-Number (NaN) value of type
  67      * {@code float}.  It is equivalent to the value returned by
  68      * {@code Float.intBitsToFloat(0x7fc00000)}.
  69      */
  70     public static final float NaN = 0.0f / 0.0f;
  71 
  72     /**
  73      * A constant holding the largest positive finite value of type
  74      * {@code float}, (2-2<sup>-23</sup>)&middot;2<sup>127</sup>.
  75      * It is equal to the hexadecimal floating-point literal
  76      * {@code 0x1.fffffeP+127f} and also equal to
  77      * {@code Float.intBitsToFloat(0x7f7fffff)}.
  78      */
  79     public static final float MAX_VALUE = 0x1.fffffeP+127f; // 3.4028235e+38f
  80 
  81     /**
  82      * A constant holding the smallest positive normal value of type
  83      * {@code float}, 2<sup>-126</sup>.  It is equal to the
  84      * hexadecimal floating-point literal {@code 0x1.0p-126f} and also
  85      * equal to {@code Float.intBitsToFloat(0x00800000)}.
  86      *
  87      * @since 1.6
  88      */
  89     public static final float MIN_NORMAL = 0x1.0p-126f; // 1.17549435E-38f
  90 
  91     /**
  92      * A constant holding the smallest positive nonzero value of type
  93      * {@code float}, 2<sup>-149</sup>. It is equal to the
  94      * hexadecimal floating-point literal {@code 0x0.000002P-126f}
  95      * and also equal to {@code Float.intBitsToFloat(0x1)}.
  96      */
  97     public static final float MIN_VALUE = 0x0.000002P-126f; // 1.4e-45f
  98 
  99     /**
 100      * Maximum exponent a finite {@code float} variable may have.  It
 101      * is equal to the value returned by {@code
 102      * Math.getExponent(Float.MAX_VALUE)}.
 103      *
 104      * @since 1.6
 105      */
 106     public static final int MAX_EXPONENT = 127;
 107 
 108     /**
 109      * Minimum exponent a normalized {@code float} variable may have.
 110      * It is equal to the value returned by {@code
 111      * Math.getExponent(Float.MIN_NORMAL)}.
 112      *
 113      * @since 1.6
 114      */
 115     public static final int MIN_EXPONENT = -126;
 116 
 117     /**
 118      * The number of bits used to represent a {@code float} value.
 119      *
 120      * @since 1.5
 121      */
 122     public static final int SIZE = 32;
 123 
 124     /**
 125      * The {@code Class} instance representing the primitive type
 126      * {@code float}.
 127      *
 128      * @since JDK1.1
 129      */
 130     public static final Class<Float> TYPE = Class.getPrimitiveClass("float");
 131 
 132     /**
 133      * Returns a string representation of the {@code float}
 134      * argument. All characters mentioned below are ASCII characters.
 135      * <ul>
 136      * <li>If the argument is NaN, the result is the string
 137      * "{@code NaN}".
 138      * <li>Otherwise, the result is a string that represents the sign and
 139      *     magnitude (absolute value) of the argument. If the sign is
 140      *     negative, the first character of the result is
 141      *     '{@code -}' (<code>'&#92;u002D'</code>); if the sign is
 142      *     positive, no sign character appears in the result. As for
 143      *     the magnitude <i>m</i>:
 144      * <ul>
 145      * <li>If <i>m</i> is infinity, it is represented by the characters
 146      *     {@code "Infinity"}; thus, positive infinity produces
 147      *     the result {@code "Infinity"} and negative infinity
 148      *     produces the result {@code "-Infinity"}.
 149      * <li>If <i>m</i> is zero, it is represented by the characters
 150      *     {@code "0.0"}; thus, negative zero produces the result
 151      *     {@code "-0.0"} and positive zero produces the result
 152      *     {@code "0.0"}.
 153      * <li> If <i>m</i> is greater than or equal to 10<sup>-3</sup> but
 154      *      less than 10<sup>7</sup>, then it is represented as the
 155      *      integer part of <i>m</i>, in decimal form with no leading
 156      *      zeroes, followed by '{@code .}'
 157      *      (<code>'&#92;u002E'</code>), followed by one or more
 158      *      decimal digits representing the fractional part of
 159      *      <i>m</i>.
 160      * <li> If <i>m</i> is less than 10<sup>-3</sup> or greater than or
 161      *      equal to 10<sup>7</sup>, then it is represented in
 162      *      so-called "computerized scientific notation." Let <i>n</i>
 163      *      be the unique integer such that 10<sup><i>n</i> </sup>&le;
 164      *      <i>m</i> {@literal <} 10<sup><i>n</i>+1</sup>; then let <i>a</i>
 165      *      be the mathematically exact quotient of <i>m</i> and
 166      *      10<sup><i>n</i></sup> so that 1 &le; <i>a</i> {@literal <} 10.
 167      *      The magnitude is then represented as the integer part of
 168      *      <i>a</i>, as a single decimal digit, followed by
 169      *      '{@code .}' (<code>'&#92;u002E'</code>), followed by
 170      *      decimal digits representing the fractional part of
 171      *      <i>a</i>, followed by the letter '{@code E}'
 172      *      (<code>'&#92;u0045'</code>), followed by a representation
 173      *      of <i>n</i> as a decimal integer, as produced by the
 174      *      method {@link java.lang.Integer#toString(int)}.
 175      *
 176      * </ul>
 177      * </ul>
 178      * How many digits must be printed for the fractional part of
 179      * <i>m</i> or <i>a</i>? There must be at least one digit
 180      * to represent the fractional part, and beyond that as many, but
 181      * only as many, more digits as are needed to uniquely distinguish
 182      * the argument value from adjacent values of type
 183      * {@code float}. That is, suppose that <i>x</i> is the
 184      * exact mathematical value represented by the decimal
 185      * representation produced by this method for a finite nonzero
 186      * argument <i>f</i>. Then <i>f</i> must be the {@code float}
 187      * value nearest to <i>x</i>; or, if two {@code float} values are
 188      * equally close to <i>x</i>, then <i>f</i> must be one of
 189      * them and the least significant bit of the significand of
 190      * <i>f</i> must be {@code 0}.
 191      *
 192      * <p>To create localized string representations of a floating-point
 193      * value, use subclasses of {@link java.text.NumberFormat}.
 194      *
 195      * @param   f   the float to be converted.
 196      * @return a string representation of the argument.
 197      */
 198     public static String toString(float f) {
 199         return new FloatingDecimal(f).toJavaFormatString();
 200     }
 201 
 202     /**
 203      * Returns a hexadecimal string representation of the
 204      * {@code float} argument. All characters mentioned below are
 205      * ASCII characters.
 206      *
 207      * <ul>
 208      * <li>If the argument is NaN, the result is the string
 209      *     "{@code NaN}".
 210      * <li>Otherwise, the result is a string that represents the sign and
 211      * magnitude (absolute value) of the argument. If the sign is negative,
 212      * the first character of the result is '{@code -}'
 213      * (<code>'&#92;u002D'</code>); if the sign is positive, no sign character
 214      * appears in the result. As for the magnitude <i>m</i>:
 215      *
 216      * <ul>
 217      * <li>If <i>m</i> is infinity, it is represented by the string
 218      * {@code "Infinity"}; thus, positive infinity produces the
 219      * result {@code "Infinity"} and negative infinity produces
 220      * the result {@code "-Infinity"}.
 221      *
 222      * <li>If <i>m</i> is zero, it is represented by the string
 223      * {@code "0x0.0p0"}; thus, negative zero produces the result
 224      * {@code "-0x0.0p0"} and positive zero produces the result
 225      * {@code "0x0.0p0"}.
 226      *
 227      * <li>If <i>m</i> is a {@code float} value with a
 228      * normalized representation, substrings are used to represent the
 229      * significand and exponent fields.  The significand is
 230      * represented by the characters {@code "0x1."}
 231      * followed by a lowercase hexadecimal representation of the rest
 232      * of the significand as a fraction.  Trailing zeros in the
 233      * hexadecimal representation are removed unless all the digits
 234      * are zero, in which case a single zero is used. Next, the
 235      * exponent is represented by {@code "p"} followed
 236      * by a decimal string of the unbiased exponent as if produced by
 237      * a call to {@link Integer#toString(int) Integer.toString} on the
 238      * exponent value.
 239      *
 240      * <li>If <i>m</i> is a {@code float} value with a subnormal
 241      * representation, the significand is represented by the
 242      * characters {@code "0x0."} followed by a
 243      * hexadecimal representation of the rest of the significand as a
 244      * fraction.  Trailing zeros in the hexadecimal representation are
 245      * removed. Next, the exponent is represented by
 246      * {@code "p-126"}.  Note that there must be at
 247      * least one nonzero digit in a subnormal significand.
 248      *
 249      * </ul>
 250      *
 251      * </ul>
 252      *
 253      * <table border>
 254      * <caption><h3>Examples</h3></caption>
 255      * <tr><th>Floating-point Value</th><th>Hexadecimal String</th>
 256      * <tr><td>{@code 1.0}</td> <td>{@code 0x1.0p0}</td>
 257      * <tr><td>{@code -1.0}</td>        <td>{@code -0x1.0p0}</td>
 258      * <tr><td>{@code 2.0}</td> <td>{@code 0x1.0p1}</td>
 259      * <tr><td>{@code 3.0}</td> <td>{@code 0x1.8p1}</td>
 260      * <tr><td>{@code 0.5}</td> <td>{@code 0x1.0p-1}</td>
 261      * <tr><td>{@code 0.25}</td>        <td>{@code 0x1.0p-2}</td>
 262      * <tr><td>{@code Float.MAX_VALUE}</td>
 263      *     <td>{@code 0x1.fffffep127}</td>
 264      * <tr><td>{@code Minimum Normal Value}</td>
 265      *     <td>{@code 0x1.0p-126}</td>
 266      * <tr><td>{@code Maximum Subnormal Value}</td>
 267      *     <td>{@code 0x0.fffffep-126}</td>
 268      * <tr><td>{@code Float.MIN_VALUE}</td>
 269      *     <td>{@code 0x0.000002p-126}</td>
 270      * </table>
 271      * @param   f   the {@code float} to be converted.
 272      * @return a hex string representation of the argument.
 273      * @since 1.5
 274      * @author Joseph D. Darcy
 275      */
 276     public static String toHexString(float f) {
 277         if (Math.abs(f) < FloatConsts.MIN_NORMAL
 278             &&  f != 0.0f ) {// float subnormal
 279             // Adjust exponent to create subnormal double, then
 280             // replace subnormal double exponent with subnormal float
 281             // exponent
 282             String s = Double.toHexString(FpUtils.scalb((double)f,
 283                                                         /* -1022+126 */
 284                                                         DoubleConsts.MIN_EXPONENT-
 285                                                         FloatConsts.MIN_EXPONENT));
 286             return s.replaceFirst("p-1022$", "p-126");
 287         }
 288         else // double string will be the same as float string
 289             return Double.toHexString(f);
 290     }
 291 
 292     /**
 293      * Returns a {@code Float} object holding the
 294      * {@code float} value represented by the argument string
 295      * {@code s}.
 296      *
 297      * <p>If {@code s} is {@code null}, then a
 298      * {@code NullPointerException} is thrown.
 299      *
 300      * <p>Leading and trailing whitespace characters in {@code s}
 301      * are ignored.  Whitespace is removed as if by the {@link
 302      * String#trim} method; that is, both ASCII space and control
 303      * characters are removed. The rest of {@code s} should
 304      * constitute a <i>FloatValue</i> as described by the lexical
 305      * syntax rules:
 306      *
 307      * <blockquote>
 308      * <dl>
 309      * <dt><i>FloatValue:</i>
 310      * <dd><i>Sign<sub>opt</sub></i> {@code NaN}
 311      * <dd><i>Sign<sub>opt</sub></i> {@code Infinity}
 312      * <dd><i>Sign<sub>opt</sub> FloatingPointLiteral</i>
 313      * <dd><i>Sign<sub>opt</sub> HexFloatingPointLiteral</i>
 314      * <dd><i>SignedInteger</i>
 315      * </dl>
 316      *
 317      * <p>
 318      *
 319      * <dl>
 320      * <dt><i>HexFloatingPointLiteral</i>:
 321      * <dd> <i>HexSignificand BinaryExponent FloatTypeSuffix<sub>opt</sub></i>
 322      * </dl>
 323      *
 324      * <p>
 325      *
 326      * <dl>
 327      * <dt><i>HexSignificand:</i>
 328      * <dd><i>HexNumeral</i>
 329      * <dd><i>HexNumeral</i> {@code .}
 330      * <dd>{@code 0x} <i>HexDigits<sub>opt</sub>
 331      *     </i>{@code .}<i> HexDigits</i>
 332      * <dd>{@code 0X}<i> HexDigits<sub>opt</sub>
 333      *     </i>{@code .} <i>HexDigits</i>
 334      * </dl>
 335      *
 336      * <p>
 337      *
 338      * <dl>
 339      * <dt><i>BinaryExponent:</i>
 340      * <dd><i>BinaryExponentIndicator SignedInteger</i>
 341      * </dl>
 342      *
 343      * <p>
 344      *
 345      * <dl>
 346      * <dt><i>BinaryExponentIndicator:</i>
 347      * <dd>{@code p}
 348      * <dd>{@code P}
 349      * </dl>
 350      *
 351      * </blockquote>
 352      *
 353      * where <i>Sign</i>, <i>FloatingPointLiteral</i>,
 354      * <i>HexNumeral</i>, <i>HexDigits</i>, <i>SignedInteger</i> and
 355      * <i>FloatTypeSuffix</i> are as defined in the lexical structure
 356      * sections of the <a
 357      * href="http://java.sun.com/docs/books/jls/html/">Java Language
 358      * Specification</a>. If {@code s} does not have the form of
 359      * a <i>FloatValue</i>, then a {@code NumberFormatException}
 360      * is thrown. Otherwise, {@code s} is regarded as
 361      * representing an exact decimal value in the usual
 362      * "computerized scientific notation" or as an exact
 363      * hexadecimal value; this exact numerical value is then
 364      * conceptually converted to an "infinitely precise"
 365      * binary value that is then rounded to type {@code float}
 366      * by the usual round-to-nearest rule of IEEE 754 floating-point
 367      * arithmetic, which includes preserving the sign of a zero
 368      * value. Finally, a {@code Float} object representing this
 369      * {@code float} value is returned.
 370      *
 371      * <p>To interpret localized string representations of a
 372      * floating-point value, use subclasses of {@link
 373      * java.text.NumberFormat}.
 374      *
 375      * <p>Note that trailing format specifiers, specifiers that
 376      * determine the type of a floating-point literal
 377      * ({@code 1.0f} is a {@code float} value;
 378      * {@code 1.0d} is a {@code double} value), do
 379      * <em>not</em> influence the results of this method.  In other
 380      * words, the numerical value of the input string is converted
 381      * directly to the target floating-point type.  In general, the
 382      * two-step sequence of conversions, string to {@code double}
 383      * followed by {@code double} to {@code float}, is
 384      * <em>not</em> equivalent to converting a string directly to
 385      * {@code float}.  For example, if first converted to an
 386      * intermediate {@code double} and then to
 387      * {@code float}, the string<br>
 388      * {@code "1.00000017881393421514957253748434595763683319091796875001d"}<br>
 389      * results in the {@code float} value
 390      * {@code 1.0000002f}; if the string is converted directly to
 391      * {@code float}, <code>1.000000<b>1</b>f</code> results.
 392      *
 393      * <p>To avoid calling this method on an invalid string and having
 394      * a {@code NumberFormatException} be thrown, the documentation
 395      * for {@link Double#valueOf Double.valueOf} lists a regular
 396      * expression which can be used to screen the input.
 397      *
 398      * @param   s   the string to be parsed.
 399      * @return  a {@code Float} object holding the value
 400      *          represented by the {@code String} argument.
 401      * @throws  NumberFormatException  if the string does not contain a
 402      *          parsable number.
 403      */
 404     public static Float valueOf(String s) throws NumberFormatException {
 405         return new Float(FloatingDecimal.readJavaFormatString(s).floatValue());
 406     }
 407 
 408     /**
 409      * Returns a {@code Float} instance representing the specified
 410      * {@code float} value.
 411      * If a new {@code Float} instance is not required, this method
 412      * should generally be used in preference to the constructor
 413      * {@link #Float(float)}, as this method is likely to yield
 414      * significantly better space and time performance by caching
 415      * frequently requested values.
 416      *
 417      * @param  f a float value.
 418      * @return a {@code Float} instance representing {@code f}.
 419      * @since  1.5
 420      */
 421     public static Float valueOf(float f) {
 422         return new Float(f);
 423     }
 424 
 425     /**
 426      * Returns a new {@code float} initialized to the value
 427      * represented by the specified {@code String}, as performed
 428      * by the {@code valueOf} method of class {@code Float}.
 429      *
 430      * @param      s   the string to be parsed.
 431      * @return the {@code float} value represented by the string
 432      *         argument.
 433      * @throws  NumberFormatException  if the string does not contain a
 434      *               parsable {@code float}.
 435      * @see        java.lang.Float#valueOf(String)
 436      * @since 1.2
 437      */
 438     public static float parseFloat(String s) throws NumberFormatException {
 439         return FloatingDecimal.readJavaFormatString(s).floatValue();
 440     }
 441 
 442     /**
 443      * Returns {@code true} if the specified number is a
 444      * Not-a-Number (NaN) value, {@code false} otherwise.
 445      *
 446      * @param   v   the value to be tested.
 447      * @return  {@code true} if the argument is NaN;
 448      *          {@code false} otherwise.
 449      */
 450     static public boolean isNaN(float v) {
 451         return (v != v);
 452     }
 453 
 454     /**
 455      * Returns {@code true} if the specified number is infinitely
 456      * large in magnitude, {@code false} otherwise.
 457      *
 458      * @param   v   the value to be tested.
 459      * @return  {@code true} if the argument is positive infinity or
 460      *          negative infinity; {@code false} otherwise.
 461      */
 462     static public boolean isInfinite(float v) {
 463         return (v == POSITIVE_INFINITY) || (v == NEGATIVE_INFINITY);
 464     }
 465 
 466     /**
 467      * The value of the Float.
 468      *
 469      * @serial
 470      */
 471     private final float value;
 472 
 473     /**
 474      * Constructs a newly allocated {@code Float} object that
 475      * represents the primitive {@code float} argument.
 476      *
 477      * @param   value   the value to be represented by the {@code Float}.
 478      */
 479     public Float(float value) {
 480         this.value = value;
 481     }
 482 
 483     /**
 484      * Constructs a newly allocated {@code Float} object that
 485      * represents the argument converted to type {@code float}.
 486      *
 487      * @param   value   the value to be represented by the {@code Float}.
 488      */
 489     public Float(double value) {
 490         this.value = (float)value;
 491     }
 492 
 493     /**
 494      * Constructs a newly allocated {@code Float} object that
 495      * represents the floating-point value of type {@code float}
 496      * represented by the string. The string is converted to a
 497      * {@code float} value as if by the {@code valueOf} method.
 498      *
 499      * @param      s   a string to be converted to a {@code Float}.
 500      * @throws  NumberFormatException  if the string does not contain a
 501      *               parsable number.
 502      * @see        java.lang.Float#valueOf(java.lang.String)
 503      */
 504     public Float(String s) throws NumberFormatException {
 505         // REMIND: this is inefficient
 506         this(valueOf(s).floatValue());
 507     }
 508 
 509     /**
 510      * Returns {@code true} if this {@code Float} value is a
 511      * Not-a-Number (NaN), {@code false} otherwise.
 512      *
 513      * @return  {@code true} if the value represented by this object is
 514      *          NaN; {@code false} otherwise.
 515      */
 516     public boolean isNaN() {
 517         return isNaN(value);
 518     }
 519 
 520     /**
 521      * Returns {@code true} if this {@code Float} value is
 522      * infinitely large in magnitude, {@code false} otherwise.
 523      *
 524      * @return  {@code true} if the value represented by this object is
 525      *          positive infinity or negative infinity;
 526      *          {@code false} otherwise.
 527      */
 528     public boolean isInfinite() {
 529         return isInfinite(value);
 530     }
 531 
 532     /**
 533      * Returns a string representation of this {@code Float} object.
 534      * The primitive {@code float} value represented by this object
 535      * is converted to a {@code String} exactly as if by the method
 536      * {@code toString} of one argument.
 537      *
 538      * @return  a {@code String} representation of this object.
 539      * @see java.lang.Float#toString(float)
 540      */
 541     public String toString() {
 542         return String.valueOf(value);
 543     }
 544 
 545     /**
 546      * Returns the value of this {@code Float} as a {@code byte} (by
 547      * casting to a {@code byte}).
 548      *
 549      * @return  the {@code float} value represented by this object
 550      *          converted to type {@code byte}
 551      */
 552     public byte byteValue() {
 553         return (byte)value;
 554     }
 555 
 556     /**
 557      * Returns the value of this {@code Float} as a {@code short} (by
 558      * casting to a {@code short}).
 559      *
 560      * @return  the {@code float} value represented by this object
 561      *          converted to type {@code short}
 562      * @since JDK1.1
 563      */
 564     public short shortValue() {
 565         return (short)value;
 566     }
 567 
 568     /**
 569      * Returns the value of this {@code Float} as an {@code int} (by
 570      * casting to type {@code int}).
 571      *
 572      * @return  the {@code float} value represented by this object
 573      *          converted to type {@code int}
 574      */
 575     public int intValue() {
 576         return (int)value;
 577     }
 578 
 579     /**
 580      * Returns value of this {@code Float} as a {@code long} (by
 581      * casting to type {@code long}).
 582      *
 583      * @return  the {@code float} value represented by this object
 584      *          converted to type {@code long}
 585      */
 586     public long longValue() {
 587         return (long)value;
 588     }
 589 
 590     /**
 591      * Returns the {@code float} value of this {@code Float} object.
 592      *
 593      * @return the {@code float} value represented by this object
 594      */
 595     public float floatValue() {
 596         return value;
 597     }
 598 
 599     /**
 600      * Returns the {@code double} value of this {@code Float} object.
 601      *
 602      * @return the {@code float} value represented by this
 603      *         object is converted to type {@code double} and the
 604      *         result of the conversion is returned.
 605      */
 606     public double doubleValue() {
 607         return (double)value;
 608     }
 609 
 610     /**
 611      * Returns a hash code for this {@code Float} object. The
 612      * result is the integer bit representation, exactly as produced
 613      * by the method {@link #floatToIntBits(float)}, of the primitive
 614      * {@code float} value represented by this {@code Float}
 615      * object.
 616      *
 617      * @return a hash code value for this object.
 618      */
 619     public int hashCode() {
 620         return floatToIntBits(value);
 621     }
 622 
 623     /**
 624 
 625      * Compares this object against the specified object.  The result
 626      * is {@code true} if and only if the argument is not
 627      * {@code null} and is a {@code Float} object that
 628      * represents a {@code float} with the same value as the
 629      * {@code float} represented by this object. For this
 630      * purpose, two {@code float} values are considered to be the
 631      * same if and only if the method {@link #floatToIntBits(float)}
 632      * returns the identical {@code int} value when applied to
 633      * each.
 634      *
 635      * <p>Note that in most cases, for two instances of class
 636      * {@code Float}, {@code f1} and {@code f2}, the value
 637      * of {@code f1.equals(f2)} is {@code true} if and only if
 638      *
 639      * <blockquote><pre>
 640      *   f1.floatValue() == f2.floatValue()
 641      * </pre></blockquote>
 642      *
 643      * <p>also has the value {@code true}. However, there are two exceptions:
 644      * <ul>
 645      * <li>If {@code f1} and {@code f2} both represent
 646      *     {@code Float.NaN}, then the {@code equals} method returns
 647      *     {@code true}, even though {@code Float.NaN==Float.NaN}
 648      *     has the value {@code false}.
 649      * <li>If {@code f1} represents {@code +0.0f} while
 650      *     {@code f2} represents {@code -0.0f}, or vice
 651      *     versa, the {@code equal} test has the value
 652      *     {@code false}, even though {@code 0.0f==-0.0f}
 653      *     has the value {@code true}.
 654      * </ul>
 655      *
 656      * This definition allows hash tables to operate properly.
 657      *
 658      * @param obj the object to be compared
 659      * @return  {@code true} if the objects are the same;
 660      *          {@code false} otherwise.
 661      * @see java.lang.Float#floatToIntBits(float)
 662      */
 663     public boolean equals(Object obj) {
 664         return (obj instanceof Float)
 665                && (floatToIntBits(((Float)obj).value) == floatToIntBits(value));
 666     }
 667 
 668     /**
 669      * Returns a representation of the specified floating-point value
 670      * according to the IEEE 754 floating-point "single format" bit
 671      * layout.
 672      *
 673      * <p>Bit 31 (the bit that is selected by the mask
 674      * {@code 0x80000000}) represents the sign of the floating-point
 675      * number.
 676      * Bits 30-23 (the bits that are selected by the mask
 677      * {@code 0x7f800000}) represent the exponent.
 678      * Bits 22-0 (the bits that are selected by the mask
 679      * {@code 0x007fffff}) represent the significand (sometimes called
 680      * the mantissa) of the floating-point number.
 681      *
 682      * <p>If the argument is positive infinity, the result is
 683      * {@code 0x7f800000}.
 684      *
 685      * <p>If the argument is negative infinity, the result is
 686      * {@code 0xff800000}.
 687      *
 688      * <p>If the argument is NaN, the result is {@code 0x7fc00000}.
 689      *
 690      * <p>In all cases, the result is an integer that, when given to the
 691      * {@link #intBitsToFloat(int)} method, will produce a floating-point
 692      * value the same as the argument to {@code floatToIntBits}
 693      * (except all NaN values are collapsed to a single
 694      * "canonical" NaN value).
 695      *
 696      * @param   value   a floating-point number.
 697      * @return the bits that represent the floating-point number.
 698      */
 699     public static int floatToIntBits(float value) {
 700         int result = floatToRawIntBits(value);
 701         // Check for NaN based on values of bit fields, maximum
 702         // exponent and nonzero significand.
 703         if ( ((result & FloatConsts.EXP_BIT_MASK) ==
 704               FloatConsts.EXP_BIT_MASK) &&
 705              (result & FloatConsts.SIGNIF_BIT_MASK) != 0)
 706             result = 0x7fc00000;
 707         return result;
 708     }
 709 
 710     /**
 711      * Returns a representation of the specified floating-point value
 712      * according to the IEEE 754 floating-point "single format" bit
 713      * layout, preserving Not-a-Number (NaN) values.
 714      *
 715      * <p>Bit 31 (the bit that is selected by the mask
 716      * {@code 0x80000000}) represents the sign of the floating-point
 717      * number.
 718      * Bits 30-23 (the bits that are selected by the mask
 719      * {@code 0x7f800000}) represent the exponent.
 720      * Bits 22-0 (the bits that are selected by the mask
 721      * {@code 0x007fffff}) represent the significand (sometimes called
 722      * the mantissa) of the floating-point number.
 723      *
 724      * <p>If the argument is positive infinity, the result is
 725      * {@code 0x7f800000}.
 726      *
 727      * <p>If the argument is negative infinity, the result is
 728      * {@code 0xff800000}.
 729      *
 730      * <p>If the argument is NaN, the result is the integer representing
 731      * the actual NaN value.  Unlike the {@code floatToIntBits}
 732      * method, {@code floatToRawIntBits} does not collapse all the
 733      * bit patterns encoding a NaN to a single "canonical"
 734      * NaN value.
 735      *
 736      * <p>In all cases, the result is an integer that, when given to the
 737      * {@link #intBitsToFloat(int)} method, will produce a
 738      * floating-point value the same as the argument to
 739      * {@code floatToRawIntBits}.
 740      *
 741      * @param   value   a floating-point number.
 742      * @return the bits that represent the floating-point number.
 743      * @since 1.3
 744      */
 745     public static native int floatToRawIntBits(float value);
 746 
 747     /**
 748      * Returns the {@code float} value corresponding to a given
 749      * bit representation.
 750      * The argument is considered to be a representation of a
 751      * floating-point value according to the IEEE 754 floating-point
 752      * "single format" bit layout.
 753      *
 754      * <p>If the argument is {@code 0x7f800000}, the result is positive
 755      * infinity.
 756      *
 757      * <p>If the argument is {@code 0xff800000}, the result is negative
 758      * infinity.
 759      *
 760      * <p>If the argument is any value in the range
 761      * {@code 0x7f800001} through {@code 0x7fffffff} or in
 762      * the range {@code 0xff800001} through
 763      * {@code 0xffffffff}, the result is a NaN.  No IEEE 754
 764      * floating-point operation provided by Java can distinguish
 765      * between two NaN values of the same type with different bit
 766      * patterns.  Distinct values of NaN are only distinguishable by
 767      * use of the {@code Float.floatToRawIntBits} method.
 768      *
 769      * <p>In all other cases, let <i>s</i>, <i>e</i>, and <i>m</i> be three
 770      * values that can be computed from the argument:
 771      *
 772      * <blockquote><pre>
 773      * int s = ((bits &gt;&gt; 31) == 0) ? 1 : -1;
 774      * int e = ((bits &gt;&gt; 23) & 0xff);
 775      * int m = (e == 0) ?
 776      *                 (bits & 0x7fffff) &lt;&lt; 1 :
 777      *                 (bits & 0x7fffff) | 0x800000;
 778      * </pre></blockquote>
 779      *
 780      * Then the floating-point result equals the value of the mathematical
 781      * expression <i>s</i>&middot;<i>m</i>&middot;2<sup><i>e</i>-150</sup>.
 782      *
 783      * <p>Note that this method may not be able to return a
 784      * {@code float} NaN with exactly same bit pattern as the
 785      * {@code int} argument.  IEEE 754 distinguishes between two
 786      * kinds of NaNs, quiet NaNs and <i>signaling NaNs</i>.  The
 787      * differences between the two kinds of NaN are generally not
 788      * visible in Java.  Arithmetic operations on signaling NaNs turn
 789      * them into quiet NaNs with a different, but often similar, bit
 790      * pattern.  However, on some processors merely copying a
 791      * signaling NaN also performs that conversion.  In particular,
 792      * copying a signaling NaN to return it to the calling method may
 793      * perform this conversion.  So {@code intBitsToFloat} may
 794      * not be able to return a {@code float} with a signaling NaN
 795      * bit pattern.  Consequently, for some {@code int} values,
 796      * {@code floatToRawIntBits(intBitsToFloat(start))} may
 797      * <i>not</i> equal {@code start}.  Moreover, which
 798      * particular bit patterns represent signaling NaNs is platform
 799      * dependent; although all NaN bit patterns, quiet or signaling,
 800      * must be in the NaN range identified above.
 801      *
 802      * @param   bits   an integer.
 803      * @return  the {@code float} floating-point value with the same bit
 804      *          pattern.
 805      */
 806     public static native float intBitsToFloat(int bits);
 807 
 808     /**
 809      * Compares two {@code Float} objects numerically.  There are
 810      * two ways in which comparisons performed by this method differ
 811      * from those performed by the Java language numerical comparison
 812      * operators ({@code <, <=, ==, >=, >}) when
 813      * applied to primitive {@code float} values:
 814      *
 815      * <ul><li>
 816      *          {@code Float.NaN} is considered by this method to
 817      *          be equal to itself and greater than all other
 818      *          {@code float} values
 819      *          (including {@code Float.POSITIVE_INFINITY}).
 820      * <li>
 821      *          {@code 0.0f} is considered by this method to be greater
 822      *          than {@code -0.0f}.
 823      * </ul>
 824      *
 825      * This ensures that the <i>natural ordering</i> of {@code Float}
 826      * objects imposed by this method is <i>consistent with equals</i>.
 827      *
 828      * @param   anotherFloat   the {@code Float} to be compared.
 829      * @return  the value {@code 0} if {@code anotherFloat} is
 830      *          numerically equal to this {@code Float}; a value
 831      *          less than {@code 0} if this {@code Float}
 832      *          is numerically less than {@code anotherFloat};
 833      *          and a value greater than {@code 0} if this
 834      *          {@code Float} is numerically greater than
 835      *          {@code anotherFloat}.
 836      *
 837      * @since   1.2
 838      * @see Comparable#compareTo(Object)
 839      */
 840     public int compareTo(Float anotherFloat) {
 841         return Float.compare(value, anotherFloat.value);
 842     }
 843 
 844     /**
 845      * Compares the two specified {@code float} values. The sign
 846      * of the integer value returned is the same as that of the
 847      * integer that would be returned by the call:
 848      * <pre>
 849      *    new Float(f1).compareTo(new Float(f2))
 850      * </pre>
 851      *
 852      * @param   f1        the first {@code float} to compare.
 853      * @param   f2        the second {@code float} to compare.
 854      * @return  the value {@code 0} if {@code f1} is
 855      *          numerically equal to {@code f2}; a value less than
 856      *          {@code 0} if {@code f1} is numerically less than
 857      *          {@code f2}; and a value greater than {@code 0}
 858      *          if {@code f1} is numerically greater than
 859      *          {@code f2}.
 860      * @since 1.4
 861      */
 862     public static int compare(float f1, float f2) {
 863        if (f1 < f2)
 864             return -1;           // Neither val is NaN, thisVal is smaller
 865         if (f1 > f2)
 866             return 1;            // Neither val is NaN, thisVal is larger
 867 
 868         int thisBits = Float.floatToIntBits(f1);
 869         int anotherBits = Float.floatToIntBits(f2);
 870 
 871         return (thisBits == anotherBits ?  0 : // Values are equal
 872                 (thisBits < anotherBits ? -1 : // (-0.0, 0.0) or (!NaN, NaN)
 873                  1));                          // (0.0, -0.0) or (NaN, !NaN)
 874     }
 875 
 876     /** use serialVersionUID from JDK 1.0.2 for interoperability */
 877     private static final long serialVersionUID = -2671257302660747028L;
 878 }