GNU Classpath (0.18) | ||
Frames | No Frames |
1: /* Double.java -- object wrapper for double 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: package java.lang; 40: 41: import gnu.classpath.Configuration; 42: 43: /** 44: * Instances of class <code>Double</code> represent primitive 45: * <code>double</code> values. 46: * 47: * Additionally, this class provides various helper functions and variables 48: * related to doubles. 49: * 50: * @author Paul Fisher 51: * @author Andrew Haley (aph@cygnus.com) 52: * @author Eric Blake (ebb9@email.byu.edu) 53: * @since 1.0 54: * @status updated to 1.4 55: */ 56: public final class Double extends Number implements Comparable 57: { 58: /** 59: * Compatible with JDK 1.0+. 60: */ 61: private static final long serialVersionUID = -9172774392245257468L; 62: 63: /** 64: * The maximum positive value a <code>double</code> may represent 65: * is 1.7976931348623157e+308. 66: */ 67: public static final double MAX_VALUE = 1.7976931348623157e+308; 68: 69: /** 70: * The minimum positive value a <code>double</code> may represent 71: * is 5e-324. 72: */ 73: public static final double MIN_VALUE = 5e-324; 74: 75: /** 76: * The value of a double representation -1.0/0.0, negative 77: * infinity. 78: */ 79: public static final double NEGATIVE_INFINITY = -1.0 / 0.0; 80: 81: /** 82: * The value of a double representing 1.0/0.0, positive infinity. 83: */ 84: public static final double POSITIVE_INFINITY = 1.0 / 0.0; 85: 86: /** 87: * All IEEE 754 values of NaN have the same value in Java. 88: */ 89: public static final double NaN = 0.0 / 0.0; 90: 91: /** 92: * The primitive type <code>double</code> is represented by this 93: * <code>Class</code> object. 94: * @since 1.1 95: */ 96: public static final Class TYPE = VMClassLoader.getPrimitiveClass('D'); 97: 98: /** 99: * The immutable value of this Double. 100: * 101: * @serial the wrapped double 102: */ 103: private final double value; 104: 105: /** 106: * Create a <code>Double</code> from the primitive <code>double</code> 107: * specified. 108: * 109: * @param value the <code>double</code> argument 110: */ 111: public Double(double value) 112: { 113: this.value = value; 114: } 115: 116: /** 117: * Create a <code>Double</code> from the specified <code>String</code>. 118: * This method calls <code>Double.parseDouble()</code>. 119: * 120: * @param s the <code>String</code> to convert 121: * @throws NumberFormatException if <code>s</code> cannot be parsed as a 122: * <code>double</code> 123: * @throws NullPointerException if <code>s</code> is null 124: * @see #parseDouble(String) 125: */ 126: public Double(String s) 127: { 128: value = parseDouble(s); 129: } 130: 131: /** 132: * Convert the <code>double</code> to a <code>String</code>. 133: * Floating-point string representation is fairly complex: here is a 134: * rundown of the possible values. "<code>[-]</code>" indicates that a 135: * negative sign will be printed if the value (or exponent) is negative. 136: * "<code><number></code>" means a string of digits ('0' to '9'). 137: * "<code><digit></code>" means a single digit ('0' to '9').<br> 138: * 139: * <table border=1> 140: * <tr><th>Value of Double</th><th>String Representation</th></tr> 141: * <tr><td>[+-] 0</td> <td><code>[-]0.0</code></td></tr> 142: * <tr><td>Between [+-] 10<sup>-3</sup> and 10<sup>7</sup>, exclusive</td> 143: * <td><code>[-]number.number</code></td></tr> 144: * <tr><td>Other numeric value</td> 145: * <td><code>[-]<digit>.<number> 146: * E[-]<number></code></td></tr> 147: * <tr><td>[+-] infinity</td> <td><code>[-]Infinity</code></td></tr> 148: * <tr><td>NaN</td> <td><code>NaN</code></td></tr> 149: * </table> 150: * 151: * Yes, negative zero <em>is</em> a possible value. Note that there is 152: * <em>always</em> a <code>.</code> and at least one digit printed after 153: * it: even if the number is 3, it will be printed as <code>3.0</code>. 154: * After the ".", all digits will be printed except trailing zeros. The 155: * result is rounded to the shortest decimal number which will parse back 156: * to the same double. 157: * 158: * <p>To create other output formats, use {@link java.text.NumberFormat}. 159: * 160: * @XXX specify where we are not in accord with the spec. 161: * 162: * @param d the <code>double</code> to convert 163: * @return the <code>String</code> representing the <code>double</code> 164: */ 165: public static String toString(double d) 166: { 167: return VMDouble.toString(d, false); 168: } 169: 170: /** 171: * Create a new <code>Double</code> object using the <code>String</code>. 172: * 173: * @param s the <code>String</code> to convert 174: * @return the new <code>Double</code> 175: * @throws NumberFormatException if <code>s</code> cannot be parsed as a 176: * <code>double</code> 177: * @throws NullPointerException if <code>s</code> is null. 178: * @see #parseDouble(String) 179: */ 180: public static Double valueOf(String s) 181: { 182: return new Double(parseDouble(s)); 183: } 184: 185: /** 186: * Parse the specified <code>String</code> as a <code>double</code>. The 187: * extended BNF grammar is as follows:<br> 188: * <pre> 189: * <em>DecodableString</em>: 190: * ( [ <code>-</code> | <code>+</code> ] <code>NaN</code> ) 191: * | ( [ <code>-</code> | <code>+</code> ] <code>Infinity</code> ) 192: * | ( [ <code>-</code> | <code>+</code> ] <em>FloatingPoint</em> 193: * [ <code>f</code> | <code>F</code> | <code>d</code> 194: * | <code>D</code>] ) 195: * <em>FloatingPoint</em>: 196: * ( { <em>Digit</em> }+ [ <code>.</code> { <em>Digit</em> } ] 197: * [ <em>Exponent</em> ] ) 198: * | ( <code>.</code> { <em>Digit</em> }+ [ <em>Exponent</em> ] ) 199: * <em>Exponent</em>: 200: * ( ( <code>e</code> | <code>E</code> ) 201: * [ <code>-</code> | <code>+</code> ] { <em>Digit</em> }+ ) 202: * <em>Digit</em>: <em><code>'0'</code> through <code>'9'</code></em> 203: * </pre> 204: * 205: * <p>NaN and infinity are special cases, to allow parsing of the output 206: * of toString. Otherwise, the result is determined by calculating 207: * <em>n * 10<sup>exponent</sup></em> to infinite precision, then rounding 208: * to the nearest double. Remember that many numbers cannot be precisely 209: * represented in floating point. In case of overflow, infinity is used, 210: * and in case of underflow, signed zero is used. Unlike Integer.parseInt, 211: * this does not accept Unicode digits outside the ASCII range. 212: * 213: * <p>If an unexpected character is found in the <code>String</code>, a 214: * <code>NumberFormatException</code> will be thrown. Leading and trailing 215: * 'whitespace' is ignored via <code>String.trim()</code>, but spaces 216: * internal to the actual number are not allowed. 217: * 218: * <p>To parse numbers according to another format, consider using 219: * {@link java.text.NumberFormat}. 220: * 221: * @XXX specify where/how we are not in accord with the spec. 222: * 223: * @param str the <code>String</code> to convert 224: * @return the <code>double</code> value of <code>s</code> 225: * @throws NumberFormatException if <code>s</code> cannot be parsed as a 226: * <code>double</code> 227: * @throws NullPointerException if <code>s</code> is null 228: * @see #MIN_VALUE 229: * @see #MAX_VALUE 230: * @see #POSITIVE_INFINITY 231: * @see #NEGATIVE_INFINITY 232: * @since 1.2 233: */ 234: public static double parseDouble(String str) 235: { 236: return VMDouble.parseDouble(str); 237: } 238: 239: /** 240: * Return <code>true</code> if the <code>double</code> has the same 241: * value as <code>NaN</code>, otherwise return <code>false</code>. 242: * 243: * @param v the <code>double</code> to compare 244: * @return whether the argument is <code>NaN</code>. 245: */ 246: public static boolean isNaN(double v) 247: { 248: // This works since NaN != NaN is the only reflexive inequality 249: // comparison which returns true. 250: return v != v; 251: } 252: 253: /** 254: * Return <code>true</code> if the <code>double</code> has a value 255: * equal to either <code>NEGATIVE_INFINITY</code> or 256: * <code>POSITIVE_INFINITY</code>, otherwise return <code>false</code>. 257: * 258: * @param v the <code>double</code> to compare 259: * @return whether the argument is (-/+) infinity. 260: */ 261: public static boolean isInfinite(double v) 262: { 263: return v == POSITIVE_INFINITY || v == NEGATIVE_INFINITY; 264: } 265: 266: /** 267: * Return <code>true</code> if the value of this <code>Double</code> 268: * is the same as <code>NaN</code>, otherwise return <code>false</code>. 269: * 270: * @return whether this <code>Double</code> is <code>NaN</code> 271: */ 272: public boolean isNaN() 273: { 274: return isNaN(value); 275: } 276: 277: /** 278: * Return <code>true</code> if the value of this <code>Double</code> 279: * is the same as <code>NEGATIVE_INFINITY</code> or 280: * <code>POSITIVE_INFINITY</code>, otherwise return <code>false</code>. 281: * 282: * @return whether this <code>Double</code> is (-/+) infinity 283: */ 284: public boolean isInfinite() 285: { 286: return isInfinite(value); 287: } 288: 289: /** 290: * Convert the <code>double</code> value of this <code>Double</code> 291: * to a <code>String</code>. This method calls 292: * <code>Double.toString(double)</code> to do its dirty work. 293: * 294: * @return the <code>String</code> representation 295: * @see #toString(double) 296: */ 297: public String toString() 298: { 299: return toString(value); 300: } 301: 302: /** 303: * Return the value of this <code>Double</code> as a <code>byte</code>. 304: * 305: * @return the byte value 306: * @since 1.1 307: */ 308: public byte byteValue() 309: { 310: return (byte) value; 311: } 312: 313: /** 314: * Return the value of this <code>Double</code> as a <code>short</code>. 315: * 316: * @return the short value 317: * @since 1.1 318: */ 319: public short shortValue() 320: { 321: return (short) value; 322: } 323: 324: /** 325: * Return the value of this <code>Double</code> as an <code>int</code>. 326: * 327: * @return the int value 328: */ 329: public int intValue() 330: { 331: return (int) value; 332: } 333: 334: /** 335: * Return the value of this <code>Double</code> as a <code>long</code>. 336: * 337: * @return the long value 338: */ 339: public long longValue() 340: { 341: return (long) value; 342: } 343: 344: /** 345: * Return the value of this <code>Double</code> as a <code>float</code>. 346: * 347: * @return the float value 348: */ 349: public float floatValue() 350: { 351: return (float) value; 352: } 353: 354: /** 355: * Return the value of this <code>Double</code>. 356: * 357: * @return the double value 358: */ 359: public double doubleValue() 360: { 361: return value; 362: } 363: 364: /** 365: * Return a hashcode representing this Object. <code>Double</code>'s hash 366: * code is calculated by:<br> 367: * <code>long v = Double.doubleToLongBits(doubleValue());<br> 368: * int hash = (int)(v^(v>>32))</code>. 369: * 370: * @return this Object's hash code 371: * @see #doubleToLongBits(double) 372: */ 373: public int hashCode() 374: { 375: long v = doubleToLongBits(value); 376: return (int) (v ^ (v >>> 32)); 377: } 378: 379: /** 380: * Returns <code>true</code> if <code>obj</code> is an instance of 381: * <code>Double</code> and represents the same double value. Unlike comparing 382: * two doubles with <code>==</code>, this treats two instances of 383: * <code>Double.NaN</code> as equal, but treats <code>0.0</code> and 384: * <code>-0.0</code> as unequal. 385: * 386: * <p>Note that <code>d1.equals(d2)</code> is identical to 387: * <code>doubleToLongBits(d1.doubleValue()) == 388: * doubleToLongBits(d2.doubleValue())</code>. 389: * 390: * @param obj the object to compare 391: * @return whether the objects are semantically equal 392: */ 393: public boolean equals(Object obj) 394: { 395: if (! (obj instanceof Double)) 396: return false; 397: 398: double d = ((Double) obj).value; 399: 400: // Avoid call to native method. However, some implementations, like gcj, 401: // are better off using floatToIntBits(value) == floatToIntBits(f). 402: // Check common case first, then check NaN and 0. 403: if (value == d) 404: return (value != 0) || (1 / value == 1 / d); 405: return isNaN(value) && isNaN(d); 406: } 407: 408: /** 409: * Convert the double to the IEEE 754 floating-point "double format" bit 410: * layout. Bit 63 (the most significant) is the sign bit, bits 62-52 411: * (masked by 0x7ff0000000000000L) represent the exponent, and bits 51-0 412: * (masked by 0x000fffffffffffffL) are the mantissa. This function 413: * collapses all versions of NaN to 0x7ff8000000000000L. The result of this 414: * function can be used as the argument to 415: * <code>Double.longBitsToDouble(long)</code> to obtain the original 416: * <code>double</code> value. 417: * 418: * @param value the <code>double</code> to convert 419: * @return the bits of the <code>double</code> 420: * @see #longBitsToDouble(long) 421: */ 422: public static long doubleToLongBits(double value) 423: { 424: return VMDouble.doubleToLongBits(value); 425: } 426: 427: /** 428: * Convert the double to the IEEE 754 floating-point "double format" bit 429: * layout. Bit 63 (the most significant) is the sign bit, bits 62-52 430: * (masked by 0x7ff0000000000000L) represent the exponent, and bits 51-0 431: * (masked by 0x000fffffffffffffL) are the mantissa. This function 432: * leaves NaN alone, rather than collapsing to a canonical value. The 433: * result of this function can be used as the argument to 434: * <code>Double.longBitsToDouble(long)</code> to obtain the original 435: * <code>double</code> value. 436: * 437: * @param value the <code>double</code> to convert 438: * @return the bits of the <code>double</code> 439: * @see #longBitsToDouble(long) 440: */ 441: public static long doubleToRawLongBits(double value) 442: { 443: return VMDouble.doubleToRawLongBits(value); 444: } 445: 446: /** 447: * Convert the argument in IEEE 754 floating-point "double format" bit 448: * layout to the corresponding float. Bit 63 (the most significant) is the 449: * sign bit, bits 62-52 (masked by 0x7ff0000000000000L) represent the 450: * exponent, and bits 51-0 (masked by 0x000fffffffffffffL) are the mantissa. 451: * This function leaves NaN alone, so that you can recover the bit pattern 452: * with <code>Double.doubleToRawLongBits(double)</code>. 453: * 454: * @param bits the bits to convert 455: * @return the <code>double</code> represented by the bits 456: * @see #doubleToLongBits(double) 457: * @see #doubleToRawLongBits(double) 458: */ 459: public static double longBitsToDouble(long bits) 460: { 461: return VMDouble.longBitsToDouble(bits); 462: } 463: 464: /** 465: * Compare two Doubles numerically by comparing their <code>double</code> 466: * values. The result is positive if the first is greater, negative if the 467: * second is greater, and 0 if the two are equal. However, this special 468: * cases NaN and signed zero as follows: NaN is considered greater than 469: * all other doubles, including <code>POSITIVE_INFINITY</code>, and positive 470: * zero is considered greater than negative zero. 471: * 472: * @param d the Double to compare 473: * @return the comparison 474: * @since 1.2 475: */ 476: public int compareTo(Double d) 477: { 478: return compare(value, d.value); 479: } 480: 481: /** 482: * Behaves like <code>compareTo(Double)</code> unless the Object 483: * is not an <code>Double</code>. 484: * 485: * @param o the object to compare 486: * @return the comparison 487: * @throws ClassCastException if the argument is not a <code>Double</code> 488: * @see #compareTo(Double) 489: * @see Comparable 490: * @since 1.2 491: */ 492: public int compareTo(Object o) 493: { 494: return compare(value, ((Double) o).value); 495: } 496: 497: /** 498: * Behaves like <code>new Double(x).compareTo(new Double(y))</code>; in 499: * other words this compares two doubles, special casing NaN and zero, 500: * without the overhead of objects. 501: * 502: * @param x the first double to compare 503: * @param y the second double to compare 504: * @return the comparison 505: * @since 1.4 506: */ 507: public static int compare(double x, double y) 508: { 509: if (isNaN(x)) 510: return isNaN(y) ? 0 : 1; 511: if (isNaN(y)) 512: return -1; 513: // recall that 0.0 == -0.0, so we convert to infinites and try again 514: if (x == 0 && y == 0) 515: return (int) (1 / x - 1 / y); 516: if (x == y) 517: return 0; 518: 519: return x > y ? 1 : -1; 520: } 521: }
GNU Classpath (0.18) |