1 /*
   2  * Copyright 1994-2009 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. 
 369      *
 370      * Note that the round-to-nearest rule also implies overflow and
 371      * underflow behaviour; if the exact value of {@code s} is large
 372      * enough in magnitude (greater than or equal to ({@link
 373      * #MAX_VALUE} + {@link Math#ulp(float) ulp(MAX_VALUE)}/2),
 374      * rounding to {@code float} will result in an infinity and if the
 375      * exact value of {@code s} is small enough in magnitude (less
 376      * than or equal to {@link #MIN_VALUE}/2), rounding to float will
 377      * result in a zero.
 378      *
 379      * Finally, after rounding a {@code Float} object representing
 380      * this {@code float} value is returned.
 381      *
 382      * <p>To interpret localized string representations of a
 383      * floating-point value, use subclasses of {@link
 384      * java.text.NumberFormat}.
 385      *
 386      * <p>Note that trailing format specifiers, specifiers that
 387      * determine the type of a floating-point literal
 388      * ({@code 1.0f} is a {@code float} value;
 389      * {@code 1.0d} is a {@code double} value), do
 390      * <em>not</em> influence the results of this method.  In other
 391      * words, the numerical value of the input string is converted
 392      * directly to the target floating-point type.  In general, the
 393      * two-step sequence of conversions, string to {@code double}
 394      * followed by {@code double} to {@code float}, is
 395      * <em>not</em> equivalent to converting a string directly to
 396      * {@code float}.  For example, if first converted to an
 397      * intermediate {@code double} and then to
 398      * {@code float}, the string<br>
 399      * {@code "1.00000017881393421514957253748434595763683319091796875001d"}<br>
 400      * results in the {@code float} value
 401      * {@code 1.0000002f}; if the string is converted directly to
 402      * {@code float}, <code>1.000000<b>1</b>f</code> results.
 403      *
 404      * <p>To avoid calling this method on an invalid string and having
 405      * a {@code NumberFormatException} be thrown, the documentation
 406      * for {@link Double#valueOf Double.valueOf} lists a regular
 407      * expression which can be used to screen the input.
 408      *
 409      * @param   s   the string to be parsed.
 410      * @return  a {@code Float} object holding the value
 411      *          represented by the {@code String} argument.
 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(FloatingDecimal.readJavaFormatString(s).floatValue());
 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  NumberFormatException  if the string does not contain a
 445      *               parsable {@code float}.
 446      * @see        java.lang.Float#valueOf(String)
 447      * @since 1.2
 448      */
 449     public static float parseFloat(String s) throws NumberFormatException {
 450         return FloatingDecimal.readJavaFormatString(s).floatValue();
 451     }
 452 
 453     /**
 454      * Returns {@code true} if the specified number is a
 455      * Not-a-Number (NaN) value, {@code false} otherwise.
 456      *
 457      * @param   v   the value to be tested.
 458      * @return  {@code true} if the argument is NaN;
 459      *          {@code false} otherwise.
 460      */
 461     static public boolean isNaN(float v) {
 462         return (v != v);
 463     }
 464 
 465     /**
 466      * Returns {@code true} if the specified number is infinitely
 467      * large in magnitude, {@code false} otherwise.
 468      *
 469      * @param   v   the value to be tested.
 470      * @return  {@code true} if the argument is positive infinity or
 471      *          negative infinity; {@code false} otherwise.
 472      */
 473     static public boolean isInfinite(float v) {
 474         return (v == POSITIVE_INFINITY) || (v == NEGATIVE_INFINITY);
 475     }
 476 
 477     /**
 478      * The value of the Float.
 479      *
 480      * @serial
 481      */
 482     private final float value;
 483 
 484     /**
 485      * Constructs a newly allocated {@code Float} object that
 486      * represents the primitive {@code float} argument.
 487      *
 488      * @param   value   the value to be represented by the {@code Float}.
 489      */
 490     public Float(float value) {
 491         this.value = value;
 492     }
 493 
 494     /**
 495      * Constructs a newly allocated {@code Float} object that
 496      * represents the argument converted to type {@code float}.
 497      *
 498      * @param   value   the value to be represented by the {@code Float}.
 499      */
 500     public Float(double value) {
 501         this.value = (float)value;
 502     }
 503 
 504     /**
 505      * Constructs a newly allocated {@code Float} object that
 506      * represents the floating-point value of type {@code float}
 507      * represented by the string. The string is converted to a
 508      * {@code float} value as if by the {@code valueOf} method.
 509      *
 510      * @param      s   a string to be converted to a {@code Float}.
 511      * @throws  NumberFormatException  if the string does not contain a
 512      *               parsable number.
 513      * @see        java.lang.Float#valueOf(java.lang.String)
 514      */
 515     public Float(String s) throws NumberFormatException {
 516         // REMIND: this is inefficient
 517         this(valueOf(s).floatValue());
 518     }
 519 
 520     /**
 521      * Returns {@code true} if this {@code Float} value is a
 522      * Not-a-Number (NaN), {@code false} otherwise.
 523      *
 524      * @return  {@code true} if the value represented by this object is
 525      *          NaN; {@code false} otherwise.
 526      */
 527     public boolean isNaN() {
 528         return isNaN(value);
 529     }
 530 
 531     /**
 532      * Returns {@code true} if this {@code Float} value is
 533      * infinitely large in magnitude, {@code false} otherwise.
 534      *
 535      * @return  {@code true} if the value represented by this object is
 536      *          positive infinity or negative infinity;
 537      *          {@code false} otherwise.
 538      */
 539     public boolean isInfinite() {
 540         return isInfinite(value);
 541     }
 542 
 543     /**
 544      * Returns a string representation of this {@code Float} object.
 545      * The primitive {@code float} value represented by this object
 546      * is converted to a {@code String} exactly as if by the method
 547      * {@code toString} of one argument.
 548      *
 549      * @return  a {@code String} representation of this object.
 550      * @see java.lang.Float#toString(float)
 551      */
 552     public String toString() {
 553         return String.valueOf(value);
 554     }
 555 
 556     /**
 557      * Returns the value of this {@code Float} as a {@code byte} (by
 558      * casting to a {@code byte}).
 559      *
 560      * @return  the {@code float} value represented by this object
 561      *          converted to type {@code byte}
 562      */
 563     public byte byteValue() {
 564         return (byte)value;
 565     }
 566 
 567     /**
 568      * Returns the value of this {@code Float} as a {@code short} (by
 569      * casting to a {@code short}).
 570      *
 571      * @return  the {@code float} value represented by this object
 572      *          converted to type {@code short}
 573      * @since JDK1.1
 574      */
 575     public short shortValue() {
 576         return (short)value;
 577     }
 578 
 579     /**
 580      * Returns the value of this {@code Float} as an {@code int} (by
 581      * casting to type {@code int}).
 582      *
 583      * @return  the {@code float} value represented by this object
 584      *          converted to type {@code int}
 585      */
 586     public int intValue() {
 587         return (int)value;
 588     }
 589 
 590     /**
 591      * Returns value of this {@code Float} as a {@code long} (by
 592      * casting to type {@code long}).
 593      *
 594      * @return  the {@code float} value represented by this object
 595      *          converted to type {@code long}
 596      */
 597     public long longValue() {
 598         return (long)value;
 599     }
 600 
 601     /**
 602      * Returns the {@code float} value of this {@code Float} object.
 603      *
 604      * @return the {@code float} value represented by this object
 605      */
 606     public float floatValue() {
 607         return value;
 608     }
 609 
 610     /**
 611      * Returns the {@code double} value of this {@code Float} object.
 612      *
 613      * @return the {@code float} value represented by this
 614      *         object is converted to type {@code double} and the
 615      *         result of the conversion is returned.
 616      */
 617     public double doubleValue() {
 618         return (double)value;
 619     }
 620 
 621     /**
 622      * Returns a hash code for this {@code Float} object. The
 623      * result is the integer bit representation, exactly as produced
 624      * by the method {@link #floatToIntBits(float)}, of the primitive
 625      * {@code float} value represented by this {@code Float}
 626      * object.
 627      *
 628      * @return a hash code value for this object.
 629      */
 630     public int hashCode() {
 631         return floatToIntBits(value);
 632     }
 633 
 634     /**
 635 
 636      * Compares this object against the specified object.  The result
 637      * is {@code true} if and only if the argument is not
 638      * {@code null} and is a {@code Float} object that
 639      * represents a {@code float} with the same value as the
 640      * {@code float} represented by this object. For this
 641      * purpose, two {@code float} values are considered to be the
 642      * same if and only if the method {@link #floatToIntBits(float)}
 643      * returns the identical {@code int} value when applied to
 644      * each.
 645      *
 646      * <p>Note that in most cases, for two instances of class
 647      * {@code Float}, {@code f1} and {@code f2}, the value
 648      * of {@code f1.equals(f2)} is {@code true} if and only if
 649      *
 650      * <blockquote><pre>
 651      *   f1.floatValue() == f2.floatValue()
 652      * </pre></blockquote>
 653      *
 654      * <p>also has the value {@code true}. However, there are two exceptions:
 655      * <ul>
 656      * <li>If {@code f1} and {@code f2} both represent
 657      *     {@code Float.NaN}, then the {@code equals} method returns
 658      *     {@code true}, even though {@code Float.NaN==Float.NaN}
 659      *     has the value {@code false}.
 660      * <li>If {@code f1} represents {@code +0.0f} while
 661      *     {@code f2} represents {@code -0.0f}, or vice
 662      *     versa, the {@code equal} test has the value
 663      *     {@code false}, even though {@code 0.0f==-0.0f}
 664      *     has the value {@code true}.
 665      * </ul>
 666      *
 667      * This definition allows hash tables to operate properly.
 668      *
 669      * @param obj the object to be compared
 670      * @return  {@code true} if the objects are the same;
 671      *          {@code false} otherwise.
 672      * @see java.lang.Float#floatToIntBits(float)
 673      */
 674     public boolean equals(Object obj) {
 675         return (obj instanceof Float)
 676                && (floatToIntBits(((Float)obj).value) == floatToIntBits(value));
 677     }
 678 
 679     /**
 680      * Returns a representation of the specified floating-point value
 681      * according to the IEEE 754 floating-point "single format" bit
 682      * layout.
 683      *
 684      * <p>Bit 31 (the bit that is selected by the mask
 685      * {@code 0x80000000}) represents the sign of the floating-point
 686      * number.
 687      * Bits 30-23 (the bits that are selected by the mask
 688      * {@code 0x7f800000}) represent the exponent.
 689      * Bits 22-0 (the bits that are selected by the mask
 690      * {@code 0x007fffff}) represent the significand (sometimes called
 691      * the mantissa) of the floating-point number.
 692      *
 693      * <p>If the argument is positive infinity, the result is
 694      * {@code 0x7f800000}.
 695      *
 696      * <p>If the argument is negative infinity, the result is
 697      * {@code 0xff800000}.
 698      *
 699      * <p>If the argument is NaN, the result is {@code 0x7fc00000}.
 700      *
 701      * <p>In all cases, the result is an integer that, when given to the
 702      * {@link #intBitsToFloat(int)} method, will produce a floating-point
 703      * value the same as the argument to {@code floatToIntBits}
 704      * (except all NaN values are collapsed to a single
 705      * "canonical" NaN value).
 706      *
 707      * @param   value   a floating-point number.
 708      * @return the bits that represent the floating-point number.
 709      */
 710     public static int floatToIntBits(float value) {
 711         int result = floatToRawIntBits(value);
 712         // Check for NaN based on values of bit fields, maximum
 713         // exponent and nonzero significand.
 714         if ( ((result & FloatConsts.EXP_BIT_MASK) ==
 715               FloatConsts.EXP_BIT_MASK) &&
 716              (result & FloatConsts.SIGNIF_BIT_MASK) != 0)
 717             result = 0x7fc00000;
 718         return result;
 719     }
 720 
 721     /**
 722      * Returns a representation of the specified floating-point value
 723      * according to the IEEE 754 floating-point "single format" bit
 724      * layout, preserving Not-a-Number (NaN) values.
 725      *
 726      * <p>Bit 31 (the bit that is selected by the mask
 727      * {@code 0x80000000}) represents the sign of the floating-point
 728      * number.
 729      * Bits 30-23 (the bits that are selected by the mask
 730      * {@code 0x7f800000}) represent the exponent.
 731      * Bits 22-0 (the bits that are selected by the mask
 732      * {@code 0x007fffff}) represent the significand (sometimes called
 733      * the mantissa) of the floating-point number.
 734      *
 735      * <p>If the argument is positive infinity, the result is
 736      * {@code 0x7f800000}.
 737      *
 738      * <p>If the argument is negative infinity, the result is
 739      * {@code 0xff800000}.
 740      *
 741      * <p>If the argument is NaN, the result is the integer representing
 742      * the actual NaN value.  Unlike the {@code floatToIntBits}
 743      * method, {@code floatToRawIntBits} does not collapse all the
 744      * bit patterns encoding a NaN to a single "canonical"
 745      * NaN value.
 746      *
 747      * <p>In all cases, the result is an integer that, when given to the
 748      * {@link #intBitsToFloat(int)} method, will produce a
 749      * floating-point value the same as the argument to
 750      * {@code floatToRawIntBits}.
 751      *
 752      * @param   value   a floating-point number.
 753      * @return the bits that represent the floating-point number.
 754      * @since 1.3
 755      */
 756     public static native int floatToRawIntBits(float value);
 757 
 758     /**
 759      * Returns the {@code float} value corresponding to a given
 760      * bit representation.
 761      * The argument is considered to be a representation of a
 762      * floating-point value according to the IEEE 754 floating-point
 763      * "single format" bit layout.
 764      *
 765      * <p>If the argument is {@code 0x7f800000}, the result is positive
 766      * infinity.
 767      *
 768      * <p>If the argument is {@code 0xff800000}, the result is negative
 769      * infinity.
 770      *
 771      * <p>If the argument is any value in the range
 772      * {@code 0x7f800001} through {@code 0x7fffffff} or in
 773      * the range {@code 0xff800001} through
 774      * {@code 0xffffffff}, the result is a NaN.  No IEEE 754
 775      * floating-point operation provided by Java can distinguish
 776      * between two NaN values of the same type with different bit
 777      * patterns.  Distinct values of NaN are only distinguishable by
 778      * use of the {@code Float.floatToRawIntBits} method.
 779      *
 780      * <p>In all other cases, let <i>s</i>, <i>e</i>, and <i>m</i> be three
 781      * values that can be computed from the argument:
 782      *
 783      * <blockquote><pre>
 784      * int s = ((bits &gt;&gt; 31) == 0) ? 1 : -1;
 785      * int e = ((bits &gt;&gt; 23) & 0xff);
 786      * int m = (e == 0) ?
 787      *                 (bits & 0x7fffff) &lt;&lt; 1 :
 788      *                 (bits & 0x7fffff) | 0x800000;
 789      * </pre></blockquote>
 790      *
 791      * Then the floating-point result equals the value of the mathematical
 792      * expression <i>s</i>&middot;<i>m</i>&middot;2<sup><i>e</i>-150</sup>.
 793      *
 794      * <p>Note that this method may not be able to return a
 795      * {@code float} NaN with exactly same bit pattern as the
 796      * {@code int} argument.  IEEE 754 distinguishes between two
 797      * kinds of NaNs, quiet NaNs and <i>signaling NaNs</i>.  The
 798      * differences between the two kinds of NaN are generally not
 799      * visible in Java.  Arithmetic operations on signaling NaNs turn
 800      * them into quiet NaNs with a different, but often similar, bit
 801      * pattern.  However, on some processors merely copying a
 802      * signaling NaN also performs that conversion.  In particular,
 803      * copying a signaling NaN to return it to the calling method may
 804      * perform this conversion.  So {@code intBitsToFloat} may
 805      * not be able to return a {@code float} with a signaling NaN
 806      * bit pattern.  Consequently, for some {@code int} values,
 807      * {@code floatToRawIntBits(intBitsToFloat(start))} may
 808      * <i>not</i> equal {@code start}.  Moreover, which
 809      * particular bit patterns represent signaling NaNs is platform
 810      * dependent; although all NaN bit patterns, quiet or signaling,
 811      * must be in the NaN range identified above.
 812      *
 813      * @param   bits   an integer.
 814      * @return  the {@code float} floating-point value with the same bit
 815      *          pattern.
 816      */
 817     public static native float intBitsToFloat(int bits);
 818 
 819     /**
 820      * Compares two {@code Float} objects numerically.  There are
 821      * two ways in which comparisons performed by this method differ
 822      * from those performed by the Java language numerical comparison
 823      * operators ({@code <, <=, ==, >=, >}) when
 824      * applied to primitive {@code float} values:
 825      *
 826      * <ul><li>
 827      *          {@code Float.NaN} is considered by this method to
 828      *          be equal to itself and greater than all other
 829      *          {@code float} values
 830      *          (including {@code Float.POSITIVE_INFINITY}).
 831      * <li>
 832      *          {@code 0.0f} is considered by this method to be greater
 833      *          than {@code -0.0f}.
 834      * </ul>
 835      *
 836      * This ensures that the <i>natural ordering</i> of {@code Float}
 837      * objects imposed by this method is <i>consistent with equals</i>.
 838      *
 839      * @param   anotherFloat   the {@code Float} to be compared.
 840      * @return  the value {@code 0} if {@code anotherFloat} is
 841      *          numerically equal to this {@code Float}; a value
 842      *          less than {@code 0} if this {@code Float}
 843      *          is numerically less than {@code anotherFloat};
 844      *          and a value greater than {@code 0} if this
 845      *          {@code Float} is numerically greater than
 846      *          {@code anotherFloat}.
 847      *
 848      * @since   1.2
 849      * @see Comparable#compareTo(Object)
 850      */
 851     public int compareTo(Float anotherFloat) {
 852         return Float.compare(value, anotherFloat.value);
 853     }
 854 
 855     /**
 856      * Compares the two specified {@code float} values. The sign
 857      * of the integer value returned is the same as that of the
 858      * integer that would be returned by the call:
 859      * <pre>
 860      *    new Float(f1).compareTo(new Float(f2))
 861      * </pre>
 862      *
 863      * @param   f1        the first {@code float} to compare.
 864      * @param   f2        the second {@code float} to compare.
 865      * @return  the value {@code 0} if {@code f1} is
 866      *          numerically equal to {@code f2}; a value less than
 867      *          {@code 0} if {@code f1} is numerically less than
 868      *          {@code f2}; and a value greater than {@code 0}
 869      *          if {@code f1} is numerically greater than
 870      *          {@code f2}.
 871      * @since 1.4
 872      */
 873     public static int compare(float f1, float f2) {
 874        if (f1 < f2)
 875             return -1;           // Neither val is NaN, thisVal is smaller
 876         if (f1 > f2)
 877             return 1;            // Neither val is NaN, thisVal is larger
 878 
 879         int thisBits = Float.floatToIntBits(f1);
 880         int anotherBits = Float.floatToIntBits(f2);
 881 
 882         return (thisBits == anotherBits ?  0 : // Values are equal
 883                 (thisBits < anotherBits ? -1 : // (-0.0, 0.0) or (!NaN, NaN)
 884                  1));                          // (0.0, -0.0) or (NaN, !NaN)
 885     }
 886 
 887     /** use serialVersionUID from JDK 1.0.2 for interoperability */
 888     private static final long serialVersionUID = -2671257302660747028L;
 889 }