GNU Classpath (0.18) | ||
Frames | No Frames |
1: /* Float.java -- object wrapper for float 2: Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2005 3: Free Software Foundation, Inc. 4: 5: This file is part of GNU Classpath. 6: 7: GNU Classpath is free software; you can redistribute it and/or modify 8: it under the terms of the GNU General Public License as published by 9: the Free Software Foundation; either version 2, or (at your option) 10: any later version. 11: 12: GNU Classpath is distributed in the hope that it will be useful, but 13: WITHOUT ANY WARRANTY; without even the implied warranty of 14: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15: General Public License for more details. 16: 17: You should have received a copy of the GNU General Public License 18: along with GNU Classpath; see the file COPYING. If not, write to the 19: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 20: 02110-1301 USA. 21: 22: Linking this library statically or dynamically with other modules is 23: making a combined work based on this library. Thus, the terms and 24: conditions of the GNU General Public License cover the whole 25: combination. 26: 27: As a special exception, the copyright holders of this library give you 28: permission to link this library with independent modules to produce an 29: executable, regardless of the license terms of these independent 30: modules, and to copy and distribute the resulting executable under 31: terms of your choice, provided that you also meet, for each linked 32: independent module, the terms and conditions of the license of that 33: module. An independent module is a module which is not derived from 34: or based on this library. If you modify this library, you may extend 35: this exception to your version of the library, but you are not 36: obligated to do so. If you do not wish to do so, delete this 37: exception statement from your version. */ 38: 39: 40: package java.lang; 41: 42: /** 43: * Instances of class <code>Float</code> represent primitive 44: * <code>float</code> values. 45: * 46: * Additionally, this class provides various helper functions and variables 47: * related to floats. 48: * 49: * @author Paul Fisher 50: * @author Andrew Haley (aph@cygnus.com) 51: * @author Eric Blake (ebb9@email.byu.edu) 52: * @since 1.0 53: * @status updated to 1.4 54: */ 55: public final class Float extends Number implements Comparable 56: { 57: /** 58: * Compatible with JDK 1.0+. 59: */ 60: private static final long serialVersionUID = -2671257302660747028L; 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: * @since 1.1 93: */ 94: public static final Class TYPE = VMClassLoader.getPrimitiveClass('F'); 95: 96: /** 97: * The immutable value of this Float. 98: * 99: * @serial the wrapped float 100: */ 101: private final float value; 102: 103: /** 104: * Create a <code>Float</code> from the primitive <code>float</code> 105: * specified. 106: * 107: * @param value the <code>float</code> argument 108: */ 109: public Float(float value) 110: { 111: this.value = value; 112: } 113: 114: /** 115: * Create a <code>Float</code> from the primitive <code>double</code> 116: * specified. 117: * 118: * @param value the <code>double</code> argument 119: */ 120: public Float(double value) 121: { 122: this.value = (float) value; 123: } 124: 125: /** 126: * Create a <code>Float</code> from the specified <code>String</code>. 127: * This method calls <code>Float.parseFloat()</code>. 128: * 129: * @param s the <code>String</code> to convert 130: * @throws NumberFormatException if <code>s</code> cannot be parsed as a 131: * <code>float</code> 132: * @throws NullPointerException if <code>s</code> is null 133: * @see #parseFloat(String) 134: */ 135: public Float(String s) 136: { 137: value = parseFloat(s); 138: } 139: 140: /** 141: * Convert the <code>float</code> to a <code>String</code>. 142: * Floating-point string representation is fairly complex: here is a 143: * rundown of the possible values. "<code>[-]</code>" indicates that a 144: * negative sign will be printed if the value (or exponent) is negative. 145: * "<code><number></code>" means a string of digits ('0' to '9'). 146: * "<code><digit></code>" means a single digit ('0' to '9').<br> 147: * 148: * <table border=1> 149: * <tr><th>Value of Float</th><th>String Representation</th></tr> 150: * <tr><td>[+-] 0</td> <td><code>[-]0.0</code></td></tr> 151: * <tr><td>Between [+-] 10<sup>-3</sup> and 10<sup>7</sup>, exclusive</td> 152: * <td><code>[-]number.number</code></td></tr> 153: * <tr><td>Other numeric value</td> 154: * <td><code>[-]<digit>.<number> 155: * E[-]<number></code></td></tr> 156: * <tr><td>[+-] infinity</td> <td><code>[-]Infinity</code></td></tr> 157: * <tr><td>NaN</td> <td><code>NaN</code></td></tr> 158: * </table> 159: * 160: * Yes, negative zero <em>is</em> a possible value. Note that there is 161: * <em>always</em> a <code>.</code> and at least one digit printed after 162: * it: even if the number is 3, it will be printed as <code>3.0</code>. 163: * After the ".", all digits will be printed except trailing zeros. The 164: * result is rounded to the shortest decimal number which will parse back 165: * to the same float. 166: * 167: * <p>To create other output formats, use {@link java.text.NumberFormat}. 168: * 169: * @XXX specify where we are not in accord with the spec. 170: * 171: * @param f the <code>float</code> to convert 172: * @return the <code>String</code> representing the <code>float</code> 173: */ 174: public static String toString(float f) 175: { 176: return VMDouble.toString(f, true); 177: } 178: 179: /** 180: * Creates a new <code>Float</code> object using the <code>String</code>. 181: * 182: * @param s the <code>String</code> to convert 183: * @return the new <code>Float</code> 184: * @throws NumberFormatException if <code>s</code> cannot be parsed as a 185: * <code>float</code> 186: * @throws NullPointerException if <code>s</code> is null 187: * @see #parseFloat(String) 188: */ 189: public static Float valueOf(String s) 190: { 191: return new Float(parseFloat(s)); 192: } 193: 194: /** 195: * Parse the specified <code>String</code> as a <code>float</code>. The 196: * extended BNF grammar is as follows:<br> 197: * <pre> 198: * <em>DecodableString</em>: 199: * ( [ <code>-</code> | <code>+</code> ] <code>NaN</code> ) 200: * | ( [ <code>-</code> | <code>+</code> ] <code>Infinity</code> ) 201: * | ( [ <code>-</code> | <code>+</code> ] <em>FloatingPoint</em> 202: * [ <code>f</code> | <code>F</code> | <code>d</code> 203: * | <code>D</code>] ) 204: * <em>FloatingPoint</em>: 205: * ( { <em>Digit</em> }+ [ <code>.</code> { <em>Digit</em> } ] 206: * [ <em>Exponent</em> ] ) 207: * | ( <code>.</code> { <em>Digit</em> }+ [ <em>Exponent</em> ] ) 208: * <em>Exponent</em>: 209: * ( ( <code>e</code> | <code>E</code> ) 210: * [ <code>-</code> | <code>+</code> ] { <em>Digit</em> }+ ) 211: * <em>Digit</em>: <em><code>'0'</code> through <code>'9'</code></em> 212: * </pre> 213: * 214: * <p>NaN and infinity are special cases, to allow parsing of the output 215: * of toString. Otherwise, the result is determined by calculating 216: * <em>n * 10<sup>exponent</sup></em> to infinite precision, then rounding 217: * to the nearest float. Remember that many numbers cannot be precisely 218: * represented in floating point. In case of overflow, infinity is used, 219: * and in case of underflow, signed zero is used. Unlike Integer.parseInt, 220: * this does not accept Unicode digits outside the ASCII range. 221: * 222: * <p>If an unexpected character is found in the <code>String</code>, a 223: * <code>NumberFormatException</code> will be thrown. Leading and trailing 224: * 'whitespace' is ignored via <code>String.trim()</code>, but spaces 225: * internal to the actual number are not allowed. 226: * 227: * <p>To parse numbers according to another format, consider using 228: * {@link java.text.NumberFormat}. 229: * 230: * @XXX specify where/how we are not in accord with the spec. 231: * 232: * @param str the <code>String</code> to convert 233: * @return the <code>float</code> value of <code>s</code> 234: * @throws NumberFormatException if <code>s</code> cannot be parsed as a 235: * <code>float</code> 236: * @throws NullPointerException if <code>s</code> is null 237: * @see #MIN_VALUE 238: * @see #MAX_VALUE 239: * @see #POSITIVE_INFINITY 240: * @see #NEGATIVE_INFINITY 241: * @since 1.2 242: */ 243: public static float parseFloat(String str) 244: { 245: // XXX Rounding parseDouble() causes some errors greater than 1 ulp from 246: // the infinitely precise decimal. 247: return (float) Double.parseDouble(str); 248: } 249: 250: /** 251: * Return <code>true</code> if the <code>float</code> has the same 252: * value as <code>NaN</code>, otherwise return <code>false</code>. 253: * 254: * @param v the <code>float</code> to compare 255: * @return whether the argument is <code>NaN</code> 256: */ 257: public static boolean isNaN(float v) 258: { 259: // This works since NaN != NaN is the only reflexive inequality 260: // comparison which returns true. 261: return v != v; 262: } 263: 264: /** 265: * Return <code>true</code> if the <code>float</code> has a value 266: * equal to either <code>NEGATIVE_INFINITY</code> or 267: * <code>POSITIVE_INFINITY</code>, otherwise return <code>false</code>. 268: * 269: * @param v the <code>float</code> to compare 270: * @return whether the argument is (-/+) infinity 271: */ 272: public static boolean isInfinite(float v) 273: { 274: return v == POSITIVE_INFINITY || v == NEGATIVE_INFINITY; 275: } 276: 277: /** 278: * Return <code>true</code> if the value of this <code>Float</code> 279: * is the same as <code>NaN</code>, otherwise return <code>false</code>. 280: * 281: * @return whether this <code>Float</code> is <code>NaN</code> 282: */ 283: public boolean isNaN() 284: { 285: return isNaN(value); 286: } 287: 288: /** 289: * Return <code>true</code> if the value of this <code>Float</code> 290: * is the same as <code>NEGATIVE_INFINITY</code> or 291: * <code>POSITIVE_INFINITY</code>, otherwise return <code>false</code>. 292: * 293: * @return whether this <code>Float</code> is (-/+) infinity 294: */ 295: public boolean isInfinite() 296: { 297: return isInfinite(value); 298: } 299: 300: /** 301: * Convert the <code>float</code> value of this <code>Float</code> 302: * to a <code>String</code>. This method calls 303: * <code>Float.toString(float)</code> to do its dirty work. 304: * 305: * @return the <code>String</code> representation 306: * @see #toString(float) 307: */ 308: public String toString() 309: { 310: return toString(value); 311: } 312: 313: /** 314: * Return the value of this <code>Float</code> as a <code>byte</code>. 315: * 316: * @return the byte value 317: * @since 1.1 318: */ 319: public byte byteValue() 320: { 321: return (byte) value; 322: } 323: 324: /** 325: * Return the value of this <code>Float</code> as a <code>short</code>. 326: * 327: * @return the short value 328: * @since 1.1 329: */ 330: public short shortValue() 331: { 332: return (short) value; 333: } 334: 335: /** 336: * Return the value of this <code>Integer</code> as an <code>int</code>. 337: * 338: * @return the int value 339: */ 340: public int intValue() 341: { 342: return (int) value; 343: } 344: 345: /** 346: * Return the value of this <code>Integer</code> as a <code>long</code>. 347: * 348: * @return the long value 349: */ 350: public long longValue() 351: { 352: return (long) value; 353: } 354: 355: /** 356: * Return the value of this <code>Float</code>. 357: * 358: * @return the float value 359: */ 360: public float floatValue() 361: { 362: return value; 363: } 364: 365: /** 366: * Return the value of this <code>Float</code> as a <code>double</code> 367: * 368: * @return the double value 369: */ 370: public double doubleValue() 371: { 372: return value; 373: } 374: 375: /** 376: * Return a hashcode representing this Object. <code>Float</code>'s hash 377: * code is calculated by calling <code>floatToIntBits(floatValue())</code>. 378: * 379: * @return this Object's hash code 380: * @see #floatToIntBits(float) 381: */ 382: public int hashCode() 383: { 384: return floatToIntBits(value); 385: } 386: 387: /** 388: * Returns <code>true</code> if <code>obj</code> is an instance of 389: * <code>Float</code> and represents the same float value. Unlike comparing 390: * two floats with <code>==</code>, this treats two instances of 391: * <code>Float.NaN</code> as equal, but treats <code>0.0</code> and 392: * <code>-0.0</code> as unequal. 393: * 394: * <p>Note that <code>f1.equals(f2)</code> is identical to 395: * <code>floatToIntBits(f1.floatValue()) == 396: * floatToIntBits(f2.floatValue())</code>. 397: * 398: * @param obj the object to compare 399: * @return whether the objects are semantically equal 400: */ 401: public boolean equals(Object obj) 402: { 403: if (! (obj instanceof Float)) 404: return false; 405: 406: float f = ((Float) obj).value; 407: 408: // Avoid call to native method. However, some implementations, like gcj, 409: // are better off using floatToIntBits(value) == floatToIntBits(f). 410: // Check common case first, then check NaN and 0. 411: if (value == f) 412: return (value != 0) || (1 / value == 1 / f); 413: return isNaN(value) && isNaN(f); 414: } 415: 416: /** 417: * Convert the float to the IEEE 754 floating-point "single format" bit 418: * layout. Bit 31 (the most significant) is the sign bit, bits 30-23 419: * (masked by 0x7f800000) represent the exponent, and bits 22-0 420: * (masked by 0x007fffff) are the mantissa. This function collapses all 421: * versions of NaN to 0x7fc00000. The result of this function can be used 422: * as the argument to <code>Float.intBitsToFloat(int)</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: * @see #intBitsToFloat(int) 428: */ 429: public static int floatToIntBits(float value) 430: { 431: return VMFloat.floatToIntBits(value); 432: } 433: 434: /** 435: * Convert the float to the IEEE 754 floating-point "single format" bit 436: * layout. Bit 31 (the most significant) is the sign bit, bits 30-23 437: * (masked by 0x7f800000) represent the exponent, and bits 22-0 438: * (masked by 0x007fffff) are the mantissa. This function leaves NaN alone, 439: * rather than collapsing to a canonical value. The result of this function 440: * can be used as the argument to <code>Float.intBitsToFloat(int)</code> to 441: * obtain the original <code>float</code> value. 442: * 443: * @param value the <code>float</code> to convert 444: * @return the bits of the <code>float</code> 445: * @see #intBitsToFloat(int) 446: */ 447: public static int floatToRawIntBits(float value) 448: { 449: return VMFloat.floatToRawIntBits(value); 450: } 451: 452: /** 453: * Convert the argument in IEEE 754 floating-point "single format" bit 454: * layout to the corresponding float. Bit 31 (the most significant) is the 455: * sign bit, bits 30-23 (masked by 0x7f800000) represent the exponent, and 456: * bits 22-0 (masked by 0x007fffff) are the mantissa. This function leaves 457: * NaN alone, so that you can recover the bit pattern with 458: * <code>Float.floatToRawIntBits(float)</code>. 459: * 460: * @param bits the bits to convert 461: * @return the <code>float</code> represented by the bits 462: * @see #floatToIntBits(float) 463: * @see #floatToRawIntBits(float) 464: */ 465: public static float intBitsToFloat(int bits) 466: { 467: return VMFloat.intBitsToFloat(bits); 468: } 469: 470: /** 471: * Compare two Floats numerically by comparing their <code>float</code> 472: * values. The result is positive if the first is greater, negative if the 473: * second is greater, and 0 if the two are equal. However, this special 474: * cases NaN and signed zero as follows: NaN is considered greater than 475: * all other floats, including <code>POSITIVE_INFINITY</code>, and positive 476: * zero is considered greater than negative zero. 477: * 478: * @param f the Float to compare 479: * @return the comparison 480: * @since 1.2 481: */ 482: public int compareTo(Float f) 483: { 484: return compare(value, f.value); 485: } 486: 487: /** 488: * Behaves like <code>compareTo(Float)</code> unless the Object 489: * is not an <code>Float</code>. 490: * 491: * @param o the object to compare 492: * @return the comparison 493: * @throws ClassCastException if the argument is not a <code>Float</code> 494: * @see #compareTo(Float) 495: * @see Comparable 496: * @since 1.2 497: */ 498: public int compareTo(Object o) 499: { 500: return compare(value, ((Float) o).value); 501: } 502: 503: /** 504: * Behaves like <code>new Float(x).compareTo(new Float(y))</code>; in 505: * other words this compares two floats, special casing NaN and zero, 506: * without the overhead of objects. 507: * 508: * @param x the first float to compare 509: * @param y the second float to compare 510: * @return the comparison 511: * @since 1.4 512: */ 513: public static int compare(float x, float y) 514: { 515: if (isNaN(x)) 516: return isNaN(y) ? 0 : 1; 517: if (isNaN(y)) 518: return -1; 519: // recall that 0.0 == -0.0, so we convert to infinities and try again 520: if (x == 0 && y == 0) 521: return (int) (1 / x - 1 / y); 522: if (x == y) 523: return 0; 524: 525: return x > y ? 1 : -1; 526: } 527: }
GNU Classpath (0.18) |