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