libjava/java/lang/Float.java

   1 /* java.lang.Float
   2    Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.lang;
  40
  41 import gnu.classpath.Configuration;
  42
  43 /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
  44  * "The Java Language Specification", ISBN 0-201-63451-1
  45  * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
  46  * Status:  Believed complete and correct.
  47  */
  48
  49 /**
  50  * Instances of class <code>Float</code> represent primitive
  51  * <code>float</code> values.
  52  *
  53  * Additionally, this class provides various helper functions and variables
  54  * related to floats.
  55  *
  56  * @author Paul Fisher
  57  * @author Andrew Haley <aph@cygnus.com>
  58  * @since JDK 1.0
  59  */
  60 public final class Float extends Number implements Comparable
  61 {
  62   /**
  63    * The maximum positive value a <code>double</code> may represent
  64    * is 3.4028235e+38f.
  65    */
  66   public static final float MAX_VALUE = 3.4028235e+38f;
  67
  68   /**
  69    * The minimum positive value a <code>float</code> may represent
  70    * is 1.4e-45.
  71    */
  72   public static final float MIN_VALUE = 1.4e-45f;
  73
  74   /**
  75    * The value of a float representation -1.0/0.0, negative infinity.
  76    */
  77   public static final float NEGATIVE_INFINITY = -1.0f/0.0f;
  78
  79   /**
  80    * The value of a float representation 1.0/0.0, positive infinity.
  81    */
  82   public static final float POSITIVE_INFINITY = 1.0f/0.0f;
  83
  84   /**
  85    * All IEEE 754 values of NaN have the same value in Java.
  86    */
  87   public static final float NaN = 0.0f/0.0f;
  88
  89   /**
  90    * The primitive type <code>float</code> is represented by this
  91    * <code>Class</code> object.
  92    */
  93   public static final Class TYPE = VMClassLoader.getPrimitiveClass('F');
  94
  95   /**
  96    * The immutable value of this Float.
  97    */
  98   private final float value;
  99
 100   private static final long serialVersionUID = -2671257302660747028L;
 101
 102   static
 103   {
 104     if (Configuration.INIT_LOAD_LIBRARY)
 105       {
 106         System.loadLibrary ("javalang");
 107       }
 108   }
 109
 110   /**
 111    * Create a <code>float</code> from the primitive <code>Float</code>
 112    * specified.
 113    *
 114    * @param value the <code>Float</code> argument
 115    */
 116   public Float (float value)
 117   {
 118     this.value = value;
 119   }
 120
 121   /**
 122    * Create a <code>Float</code> from the primitive <code>double</code>
 123    * specified.
 124    *
 125    * @param value the <code>double</code> argument
 126    */
 127   public Float (double value)
 128   {
 129     this.value = (float)value;
 130   }
 131
 132   /**
 133    * Create a <code>Float</code> from the specified <code>String</code>.
 134    *
 135    * This method calls <code>Float.parseFloat()</code>.
 136    *
 137    * @exception NumberFormatException when the <code>String</code> cannot
 138    *            be parsed into a <code>Float</code>.
 139    * @param s the <code>String</code> to convert
 140    * @see #parseFloat(java.lang.String)
 141    */
 142   public Float (String s) throws NumberFormatException
 143   {
 144     this.value = parseFloat (s);
 145   }
 146
 147   /**
 148    * Parse the specified <code>String</code> as a <code>float</code>.
 149    *
 150    * The number is really read as <em>n * 10<sup>exponent</sup></em>.  The
 151    * first number is <em>n</em>, and if there is an "<code>E</code>"
 152    * ("<code>e</code>" is also acceptable), then the integer after that is
 153    * the exponent.
 154    * <P>
 155    * Here are the possible forms the number can take:
 156    * <BR>
 157    * <TABLE BORDER=1>
 158    *     <TR><TH>Form</TH><TH>Examples</TH></TR>
 159    *     <TR><TD><CODE>[+-]&lt;number&gt;[.]</CODE></TD><TD>345., -10, 12</TD></TR>
 160    *     <TR><TD><CODE>[+-]&lt;number&gt;.&lt;number&gt;</CODE></TD><TD>40.2, 80.00, -12.30</TD></TR>
 161    *     <TR><TD><CODE>[+-]&lt;number&gt;[.]E[+-]&lt;number&gt;</CODE></TD><TD>80E12, -12e+7, 4.E-123</TD></TR>
 162    *     <TR><TD><CODE>[+-]&lt;number&gt;.&lt;number&gt;E[+-]&lt;number&gt;</CODE></TD><TD>6.02e-22, -40.2E+6, 12.3e9</TD></TR>
 163    * </TABLE>
 164    *
 165    * "<code>[+-]</code>" means either a plus or minus sign may go there, or
 166    * neither, in which case + is assumed.
 167    * <BR>
 168    * "<code>[.]</code>" means a dot may be placed here, but is optional.
 169    * <BR>
 170    * "<code>&lt;number&gt;</code>" means a string of digits (0-9), basically
 171    * an integer.  "<code>&lt;number&gt;.&lt;number&gt;</code>" is basically
 172    * a real number, a floating-point value.
 173    * <P>
 174    * Remember that a <code>float</code> has a limited range.  If the
 175    * number you specify is greater than <code>Float.MAX_VALUE</code> or less
 176    * than <code>-Float.MAX_VALUE</code>, it will be set at
 177    * <code>Float.POSITIVE_INFINITY</code> or
 178    * <code>Float.NEGATIVE_INFINITY</code>, respectively.
 179    * <P>
 180    *
 181    * Note also that <code>float</code> does not have perfect precision.  Many
 182    * numbers cannot be precisely represented.  The number you specify
 183    * will be rounded to the nearest representable value.
 184    * <code>Float.MIN_VALUE</code> is the margin of error for <code>float</code>
 185    * values.
 186    * <P>
 187    * If an unexpected character is found in the <code>String</code>, a
 188    * <code>NumberFormatException</code> will be thrown.  Spaces are not
 189    * allowed and will cause this exception to be thrown.
 190    *
 191    * @XXX specify where/how we are not in accord with the spec.
 192    *
 193    * @param str the <code>String</code> to convert
 194    * @return the value of the <code>String</code> as a <code>float</code>.
 195    * @exception NumberFormatException when the string cannot be parsed to a
 196    *            <code>float</code>.
 197    * @since JDK 1.2
 198    * @see #MIN_VALUE
 199    * @see #MAX_VALUE
 200    * @see #POSITIVE_INFINITY
 201    * @see #NEGATIVE_INFINITY
 202    */
 203   public static float parseFloat (String s) throws NumberFormatException
 204   {
 205     // The spec says that parseFloat() should work like
 206     // Double.valueOf().  This is equivalent, in our implementation,
 207     // but more efficient.
 208     return (float) Double.parseDouble (s);
 209   }
 210
 211   /**
 212    * Convert the <code>float</code> value of this <code>Float</code>
 213    * to a <code>String</code>.  This method calls
 214    * <code>Float.toString(float)</code> to do its dirty work.
 215    *
 216    * @return the <code>String</code> representation of this <code>Float</code>.
 217    * @see #toString(float)
 218    */
 219   public String toString ()
 220   {
 221     return toString (value);
 222   }
 223
 224   /**
 225    * If the <code>Object</code> is not <code>null</code>, is an
 226    * <code>instanceof</code> <code>Float</code>, and represents
 227    * the same primitive <code>float</code> value return
 228    * <code>true</code>.  Otherwise <code>false</code> is returned.
 229    * <p>
 230    * Note that there are two differences between <code>==</code> and
 231    * <code>equals()</code>. <code>0.0f == -0.0f</code> returns <code>true</code>
 232    * but <code>new Float(0.0f).equals(new Float(-0.0f))</code> returns
 233    * <code>false</code>. And <code>Float.NaN == Float.NaN</code> returns
 234    * <code>false</code>, but
 235    * <code>new Float(Float.NaN).equals(new Float(Float.NaN))</code> returns
 236    * <code>true</code>.
 237    *
 238    * @param obj the object to compare to
 239    * @return whether the objects are semantically equal.
 240    */
 241   public boolean equals (Object obj)
 242   {
 243     if (!(obj instanceof Float))
 244       return false;
 245
 246     float f = ((Float) obj).value;
 247
 248     // GCJ LOCAL: this implementation is probably faster than
 249     // Classpath's, especially once we inline floatToIntBits.
 250     return floatToIntBits (value) == floatToIntBits (f);
 251     // END GCJ LOCAL
 252   }
 253
 254   /**
 255    * Return a hashcode representing this Object.
 256    * <code>Float</code>'s hash code is calculated by calling the
 257    * <code>floatToIntBits()</code> function.
 258    * @return this Object's hash code.
 259    * @see java.lang.Float.floatToIntBits(float)
 260    */
 261   public int hashCode ()
 262   {
 263     return floatToIntBits (value);
 264   }
 265
 266   /**
 267    * Return the value of this <code>Double</code> when cast to an
 268    * <code>int</code>.
 269    */
 270   public int intValue ()
 271   {
 272     return (int) value;
 273   }
 274
 275   /**
 276    * Return the value of this <code>Double</code> when cast to a
 277    * <code>long</code>.
 278    */
 279   public long longValue ()
 280   {
 281     return (long) value;
 282   }
 283
 284   /**
 285    * Return the value of this <code>Double</code> when cast to a
 286    * <code>float</code>.
 287    */
 288   public float floatValue ()
 289   {
 290     return (float) value;
 291   }
 292
 293   /**
 294    * Return the primitive <code>double</code> value represented by this
 295    * <code>Double</code>.
 296    */
 297   public double doubleValue ()
 298   {
 299     return (double) value;
 300   }
 301
 302   /**
 303    * Convert the <code>float</code> to a <code>String</code>.
 304    * <P>
 305    *
 306    * Floating-point string representation is fairly complex: here is a
 307    * rundown of the possible values.  "<CODE>[-]</CODE>" indicates that a
 308    * negative sign will be printed if the value (or exponent) is negative.
 309    * "<CODE>&lt;number&gt;</CODE>" means a string of digits (0-9).
 310    * "<CODE>&lt;digit&gt;</CODE>" means a single digit (0-9).
 311    * <P>
 312    *
 313    * <TABLE BORDER=1>
 314    * <TR><TH>Value of Float</TH><TH>String Representation</TH></TR>
 315    * <TR>
 316    *     <TD>[+-] 0</TD>
 317    *     <TD>[<CODE>-</CODE>]<CODE>0.0</CODE></TD>
 318    * </TR>
 319    * <TR>
 320    *     <TD>Between [+-] 10<SUP>-3</SUP> and 10<SUP>7</SUP></TD>
 321    *     <TD><CODE>[-]number.number</CODE></TD>
 322    * </TR>
 323    * <TR>
 324    *     <TD>Other numeric value</TD>
 325    *     <TD><CODE>[-]&lt;digit&gt;.&lt;number&gt;E[-]&lt;number&gt;</CODE></TD>
 326    * </TR>
 327    * <TR>
 328    *     <TD>[+-] infinity</TD>
 329    *     <TD><CODE>[-]Infinity</CODE></TD>
 330    * </TR>
 331    * <TR>
 332    *     <TD>NaN</TD>
 333    *     <TD><CODE>NaN</CODE></TD>
 334    * </TR>
 335    * </TABLE>
 336    *
 337    * Yes, negative zero <EM>is</EM> a possible value.  Note that there is
 338    * <EM>always</EM> a <CODE>.</CODE> and at least one digit printed after
 339    * it: even if the number is 3, it will be printed as <CODE>3.0</CODE>.
 340    * After the ".", all digits will be printed except trailing zeros.  No
 341    * truncation or rounding is done by this function.
 342    *
 343    * @XXX specify where we are not in accord with the spec.
 344    *
 345    * @param f the <code>float</code> to convert
 346    * @return the <code>String</code> representing the <code>float</code>.
 347    */
 348   public static String toString (float f)
 349   {
 350     return Double.toString ((double) f, true);
 351   }
 352
 353   /**
 354    * Return the result of calling <code>new Float(java.lang.String)</code>.
 355    *
 356    * @param s the <code>String</code> to convert to a <code>Float</code>.
 357    * @return a new <code>Float</code> representing the <code>String</code>'s
 358    *         numeric value.
 359    *
 360    * @exception NumberFormatException thrown if <code>String</code> cannot
 361    * be parsed as a <code>double</code>.
 362    * @see #Float(java.lang.String)
 363    * @see #parseFloat(java.lang.String)
 364    */
 365   public static Float valueOf (String s) throws NumberFormatException
 366   {
 367     return new Float (s);
 368   }
 369
 370   /**
 371    * Return <code>true</code> if the value of this <code>Float</code>
 372    * is the same as <code>NaN</code>, otherwise return <code>false</code>.
 373    * @return whether this <code>Float</code> is <code>NaN</code>.
 374    */
 375   public boolean isNaN ()
 376   {
 377     return isNaN (value);
 378   }
 379
 380   /**
 381    * Return <code>true</code> if the <code>float</code> has the same
 382    * value as <code>NaN</code>, otherwise return <code>false</code>.
 383    *
 384    * @param v the <code>float</code> to compare
 385    * @return whether the argument is <code>NaN</code>.
 386    */
 387   public static boolean isNaN (float v)
 388   {
 389     // This works since NaN != NaN is the only reflexive inequality
 390     // comparison which returns true.
 391     return v != v;
 392   }
 393
 394   /**
 395    * Return <code>true</code> if the value of this <code>Float</code>
 396    * is the same as <code>NEGATIVE_INFINITY</code> or
 397    * <code>POSITIVE_INFINITY</code>, otherwise return <code>false</code>.
 398    *
 399    * @return whether this <code>Float</code> is (-/+) infinity.
 400    */
 401   public boolean isInfinite ()
 402   {
 403     return isInfinite (value);
 404   }
 405
 406   /**
 407    * Return <code>true</code> if the <code>float</code> has a value
 408    * equal to either <code>NEGATIVE_INFINITY</code> or
 409    * <code>POSITIVE_INFINITY</code>, otherwise return <code>false</code>.
 410    *
 411    * @param v the <code>float</code> to compare
 412    * @return whether the argument is (-/+) infinity.
 413    */
 414   public static boolean isInfinite (float v)
 415   {
 416     return (v == POSITIVE_INFINITY || v == NEGATIVE_INFINITY);
 417   }
 418
 419   /**
 420    * Return the int bits of the specified <code>float</code>.
 421    * The result of this function can be used as the argument to
 422    * <code>Float.intBitsToFloat(long)</code> to obtain the
 423    * original <code>float</code> value.
 424    *
 425    * @param value the <code>float</code> to convert
 426    * @return the bits of the <code>float</code>.
 427    */
 428   public static native int floatToIntBits (float value);
 429
 430   /**
 431    * Return the int bits of the specified <code>float</code>.
 432    * The result of this function can be used as the argument to
 433    * <code>Float.intBitsToFloat(long)</code> to obtain the
 434    * original <code>float</code> value.  The difference between
 435    * this function and <code>floatToIntBits</code> is that this
 436    * function does not collapse NaN values.
 437    *
 438    * @param value the <code>float</code> to convert
 439    * @return the bits of the <code>float</code>.
 440    */
 441   public static native int floatToRawIntBits (float value);
 442
 443   /**
 444    * Return the <code>float</code> represented by the long
 445    * bits specified.
 446    *
 447    * @param bits the long bits representing a <code>double</code>
 448    * @return the <code>float</code> represented by the bits.
 449    */
 450   public static native float intBitsToFloat (int bits);
 451
 452   /**
 453    * Returns 0 if the <code>float</code> value of the argument is
 454    * equal to the value of this <code>Float</code>.  Returns a number
 455    * less than zero if the value of this <code>Float</code> is less
 456    * than the <code>Float</code> value of the argument, and returns a
 457    * number greater than zero if the value of this <code>Float</code>
 458    * is greater than the <code>float</code> value of the argument.
 459    * <br>
 460    * <code>Float.NaN</code> is greater than any number other than itself,
 461    * even <code>Float.POSITIVE_INFINITY</code>.
 462    * <br>
 463    * <code>0.0</code> is greater than <code>-0.0</code>.
 464    *
 465    * @param f the Float to compare to.
 466    * @return  0 if the <code>Float</code>s are the same, &lt; 0 if this
 467    *          <code>Float</code> is less than the <code>Float</code> in
 468    *          in question, or &gt; 0 if it is greater.
 469    *
 470    * @since 1.2
 471    */
 472   public int compareTo (Float f)
 473   {
 474     return compare (value, f.value);
 475   }
 476
 477   /**
 478    * Returns 0 if the first argument is equal to the second argument.
 479    * Returns a number less than zero if the first argument is less than the
 480    * second argument, and returns a number greater than zero if the first
 481    * argument is greater than the second argument.
 482    * <br>
 483    * <code>Float.NaN</code> is greater than any number other than itself,
 484    * even <code>Float.POSITIVE_INFINITY</code>.
 485    * <br>
 486    * <code>0.0</code> is greater than <code>-0.0</code>.
 487    *
 488    * @param x the first float to compare.
 489    * @param y the second float to compare.
 490    * @return  0 if the arguments are the same, &lt; 0 if the
 491    *          first argument is less than the second argument in
 492    *          in question, or &gt; 0 if it is greater.
 493    * @since 1.4
 494    */
 495   public static int compare (float x, float y)
 496   {
 497     if (isNaN (x))
 498       return isNaN (y) ? 0 : 1;
 499     if (isNaN (y))
 500       return -1;
 501     // recall that 0.0 == -0.0, so we convert to infinities and try again
 502     if (x == 0 && y == 0)
 503       return (int) (1 / x - 1 / y);
 504     if (x == y)
 505       return 0;
 506
 507     return x > y ? 1 : -1;
 508   }
 509
 510   /**
 511    * Compares the specified <code>Object</code> to this <code>Float</code>
 512    * if and only if the <code>Object</code> is an instanceof
 513    * <code>Float</code>.
 514    * Otherwise it throws a <code>ClassCastException</code>
 515    *
 516    * @param o the Object to compare to.
 517    * @return  0 if the <code>Float</code>s are the same, &lt; 0 if this
 518    *          <code>Float</code> is less than the <code>Float</code> in
 519    *          in question, or &gt; 0 if it is greater.
 520    * @throws ClassCastException if the argument is not a <code>Float</code>
 521    *
 522    * @since 1.2
 523    */
 524   public int compareTo (Object o)
 525   {
 526     return compareTo ((Float) o);
 527   }
 528 }