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: 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 VMDouble.toString(d, false); 173: } 174: 175: /** 176: * Convert a double value to a hexadecimal string. This converts as 177: * follows: 178: * <ul> 179: * <li> A NaN value is converted to the string "NaN". 180: * <li> Positive infinity is converted to the string "Infinity". 181: * <li> Negative infinity is converted to the string "-Infinity". 182: * <li> For all other values, the first character of the result is '-' 183: * if the value is negative. This is followed by '0x1.' if the 184: * value is normal, and '0x0.' if the value is denormal. This is 185: * then followed by a (lower-case) hexadecimal representation of the 186: * mantissa, with leading zeros as required for denormal values. 187: * The next character is a 'p', and this is followed by a decimal 188: * representation of the unbiased exponent. 189: * </ul> 190: * @param d the double value 191: * @return the hexadecimal string representation 192: * @since 1.5 193: */ 194: public static String toHexString(double d) 195: { 196: if (isNaN(d)) 197: return "NaN"; 198: if (isInfinite(d)) 199: return d < 0 ? "-Infinity" : "Infinity"; 200: 201: long bits = doubleToLongBits(d); 202: StringBuilder result = new StringBuilder(); 203: 204: if (bits < 0) 205: result.append('-'); 206: result.append("0x"); 207: 208: final int mantissaBits = 52; 209: final int exponentBits = 11; 210: long mantMask = (1L << mantissaBits) - 1; 211: long mantissa = bits & mantMask; 212: long expMask = (1L << exponentBits) - 1; 213: long exponent = (bits >>> mantissaBits) & expMask; 214: 215: result.append(exponent == 0 ? '0' : '1'); 216: result.append('.'); 217: result.append(Long.toHexString(mantissa)); 218: if (exponent == 0 && mantissa != 0) 219: { 220: // Treat denormal specially by inserting '0's to make 221: // the length come out right. The constants here are 222: // to account for things like the '0x'. 223: int offset = 4 + ((bits < 0) ? 1 : 0); 224: // The silly +3 is here to keep the code the same between 225: // the Float and Double cases. In Float the value is 226: // not a multiple of 4. 227: int desiredLength = offset + (mantissaBits + 3) / 4; 228: while (result.length() < desiredLength) 229: result.insert(offset, '0'); 230: } 231: result.append('p'); 232: if (exponent == 0 && mantissa == 0) 233: { 234: // Zero, so do nothing special. 235: } 236: else 237: { 238: // Apply bias. 239: boolean denormal = exponent == 0; 240: exponent -= (1 << (exponentBits - 1)) - 1; 241: // Handle denormal. 242: if (denormal) 243: ++exponent; 244: } 245: 246: result.append(Long.toString(exponent)); 247: return result.toString(); 248: } 249: 250: /** 251: * Returns a <code>Double</code> object wrapping the value. 252: * In contrast to the <code>Double</code> constructor, this method 253: * may cache some values. It is used by boxing conversion. 254: * 255: * @param val the value to wrap 256: * @return the <code>Double</code> 257: * 258: * @since 1.5 259: */ 260: public static Double valueOf(double val) 261: { 262: // We don't actually cache, but we could. 263: return new Double(val); 264: } 265: 266: /** 267: * Create a new <code>Double</code> object using the <code>String</code>. 268: * 269: * @param s the <code>String</code> to convert 270: * @return the new <code>Double</code> 271: * @throws NumberFormatException if <code>s</code> cannot be parsed as a 272: * <code>double</code> 273: * @throws NullPointerException if <code>s</code> is null. 274: * @see #parseDouble(String) 275: */ 276: public static Double valueOf(String s) 277: { 278: return new Double(parseDouble(s)); 279: } 280: 281: /** 282: * Parse the specified <code>String</code> as a <code>double</code>. The 283: * extended BNF grammar is as follows:<br> 284: * <pre> 285: * <em>DecodableString</em>: 286: * ( [ <code>-</code> | <code>+</code> ] <code>NaN</code> ) 287: * | ( [ <code>-</code> | <code>+</code> ] <code>Infinity</code> ) 288: * | ( [ <code>-</code> | <code>+</code> ] <em>FloatingPoint</em> 289: * [ <code>f</code> | <code>F</code> | <code>d</code> 290: * | <code>D</code>] ) 291: * <em>FloatingPoint</em>: 292: * ( { <em>Digit</em> }+ [ <code>.</code> { <em>Digit</em> } ] 293: * [ <em>Exponent</em> ] ) 294: * | ( <code>.</code> { <em>Digit</em> }+ [ <em>Exponent</em> ] ) 295: * <em>Exponent</em>: 296: * ( ( <code>e</code> | <code>E</code> ) 297: * [ <code>-</code> | <code>+</code> ] { <em>Digit</em> }+ ) 298: * <em>Digit</em>: <em><code>'0'</code> through <code>'9'</code></em> 299: * </pre> 300: * 301: * <p>NaN and infinity are special cases, to allow parsing of the output 302: * of toString. Otherwise, the result is determined by calculating 303: * <em>n * 10<sup>exponent</sup></em> to infinite precision, then rounding 304: * to the nearest double. Remember that many numbers cannot be precisely 305: * represented in floating point. In case of overflow, infinity is used, 306: * and in case of underflow, signed zero is used. Unlike Integer.parseInt, 307: * this does not accept Unicode digits outside the ASCII range. 308: * 309: * <p>If an unexpected character is found in the <code>String</code>, a 310: * <code>NumberFormatException</code> will be thrown. Leading and trailing 311: * 'whitespace' is ignored via <code>String.trim()</code>, but spaces 312: * internal to the actual number are not allowed. 313: * 314: * <p>To parse numbers according to another format, consider using 315: * {@link java.text.NumberFormat}. 316: * 317: * @XXX specify where/how we are not in accord with the spec. 318: * 319: * @param str the <code>String</code> to convert 320: * @return the <code>double</code> value of <code>s</code> 321: * @throws NumberFormatException if <code>s</code> cannot be parsed as a 322: * <code>double</code> 323: * @throws NullPointerException if <code>s</code> is null 324: * @see #MIN_VALUE 325: * @see #MAX_VALUE 326: * @see #POSITIVE_INFINITY 327: * @see #NEGATIVE_INFINITY 328: * @since 1.2 329: */ 330: public static double parseDouble(String str) 331: { 332: return VMDouble.parseDouble(str); 333: } 334: 335: /** 336: * Return <code>true</code> if the <code>double</code> has the same 337: * value as <code>NaN</code>, otherwise return <code>false</code>. 338: * 339: * @param v the <code>double</code> to compare 340: * @return whether the argument is <code>NaN</code>. 341: */ 342: public static boolean isNaN(double v) 343: { 344: // This works since NaN != NaN is the only reflexive inequality 345: // comparison which returns true. 346: return v != v; 347: } 348: 349: /** 350: * Return <code>true</code> if the <code>double</code> has a value 351: * equal to either <code>NEGATIVE_INFINITY</code> or 352: * <code>POSITIVE_INFINITY</code>, otherwise return <code>false</code>. 353: * 354: * @param v the <code>double</code> to compare 355: * @return whether the argument is (-/+) infinity. 356: */ 357: public static boolean isInfinite(double v) 358: { 359: return v == POSITIVE_INFINITY || v == NEGATIVE_INFINITY; 360: } 361: 362: /** 363: * Return <code>true</code> if the value of this <code>Double</code> 364: * is the same as <code>NaN</code>, otherwise return <code>false</code>. 365: * 366: * @return whether this <code>Double</code> is <code>NaN</code> 367: */ 368: public boolean isNaN() 369: { 370: return isNaN(value); 371: } 372: 373: /** 374: * Return <code>true</code> if the value of this <code>Double</code> 375: * is the same as <code>NEGATIVE_INFINITY</code> or 376: * <code>POSITIVE_INFINITY</code>, otherwise return <code>false</code>. 377: * 378: * @return whether this <code>Double</code> is (-/+) infinity 379: */ 380: public boolean isInfinite() 381: { 382: return isInfinite(value); 383: } 384: 385: /** 386: * Convert the <code>double</code> value of this <code>Double</code> 387: * to a <code>String</code>. This method calls 388: * <code>Double.toString(double)</code> to do its dirty work. 389: * 390: * @return the <code>String</code> representation 391: * @see #toString(double) 392: */ 393: public String toString() 394: { 395: return toString(value); 396: } 397: 398: /** 399: * Return the value of this <code>Double</code> as a <code>byte</code>. 400: * 401: * @return the byte value 402: * @since 1.1 403: */ 404: public byte byteValue() 405: { 406: return (byte) value; 407: } 408: 409: /** 410: * Return the value of this <code>Double</code> as a <code>short</code>. 411: * 412: * @return the short value 413: * @since 1.1 414: */ 415: public short shortValue() 416: { 417: return (short) value; 418: } 419: 420: /** 421: * Return the value of this <code>Double</code> as an <code>int</code>. 422: * 423: * @return the int value 424: */ 425: public int intValue() 426: { 427: return (int) value; 428: } 429: 430: /** 431: * Return the value of this <code>Double</code> as a <code>long</code>. 432: * 433: * @return the long value 434: */ 435: public long longValue() 436: { 437: return (long) value; 438: } 439: 440: /** 441: * Return the value of this <code>Double</code> as a <code>float</code>. 442: * 443: * @return the float value 444: */ 445: public float floatValue() 446: { 447: return (float) value; 448: } 449: 450: /** 451: * Return the value of this <code>Double</code>. 452: * 453: * @return the double value 454: */ 455: public double doubleValue() 456: { 457: return value; 458: } 459: 460: /** 461: * Return a hashcode representing this Object. <code>Double</code>'s hash 462: * code is calculated by:<br> 463: * <code>long v = Double.doubleToLongBits(doubleValue());<br> 464: * int hash = (int)(v^(v>>32))</code>. 465: * 466: * @return this Object's hash code 467: * @see #doubleToLongBits(double) 468: */ 469: public int hashCode() 470: { 471: long v = doubleToLongBits(value); 472: return (int) (v ^ (v >>> 32)); 473: } 474: 475: /** 476: * Returns <code>true</code> if <code>obj</code> is an instance of 477: * <code>Double</code> and represents the same double value. Unlike comparing 478: * two doubles with <code>==</code>, this treats two instances of 479: * <code>Double.NaN</code> as equal, but treats <code>0.0</code> and 480: * <code>-0.0</code> as unequal. 481: * 482: * <p>Note that <code>d1.equals(d2)</code> is identical to 483: * <code>doubleToLongBits(d1.doubleValue()) == 484: * doubleToLongBits(d2.doubleValue())</code>. 485: * 486: * @param obj the object to compare 487: * @return whether the objects are semantically equal 488: */ 489: public boolean equals(Object obj) 490: { 491: if (! (obj instanceof Double)) 492: return false; 493: 494: double d = ((Double) obj).value; 495: 496: // Avoid call to native method. However, some implementations, like gcj, 497: // are better off using floatToIntBits(value) == floatToIntBits(f). 498: // Check common case first, then check NaN and 0. 499: if (value == d) 500: return (value != 0) || (1 / value == 1 / d); 501: return isNaN(value) && isNaN(d); 502: } 503: 504: /** 505: * Convert the double to the IEEE 754 floating-point "double format" bit 506: * layout. Bit 63 (the most significant) is the sign bit, bits 62-52 507: * (masked by 0x7ff0000000000000L) represent the exponent, and bits 51-0 508: * (masked by 0x000fffffffffffffL) are the mantissa. This function 509: * collapses all versions of NaN to 0x7ff8000000000000L. The result of this 510: * function can be used as the argument to 511: * <code>Double.longBitsToDouble(long)</code> to obtain the original 512: * <code>double</code> value. 513: * 514: * @param value the <code>double</code> to convert 515: * @return the bits of the <code>double</code> 516: * @see #longBitsToDouble(long) 517: */ 518: public static long doubleToLongBits(double value) 519: { 520: return VMDouble.doubleToLongBits(value); 521: } 522: 523: /** 524: * Convert the double to the IEEE 754 floating-point "double format" bit 525: * layout. Bit 63 (the most significant) is the sign bit, bits 62-52 526: * (masked by 0x7ff0000000000000L) represent the exponent, and bits 51-0 527: * (masked by 0x000fffffffffffffL) are the mantissa. This function 528: * leaves NaN alone, rather than collapsing to a canonical value. The 529: * result of this function can be used as the argument to 530: * <code>Double.longBitsToDouble(long)</code> to obtain the original 531: * <code>double</code> value. 532: * 533: * @param value the <code>double</code> to convert 534: * @return the bits of the <code>double</code> 535: * @see #longBitsToDouble(long) 536: */ 537: public static long doubleToRawLongBits(double value) 538: { 539: return VMDouble.doubleToRawLongBits(value); 540: } 541: 542: /** 543: * Convert the argument in IEEE 754 floating-point "double format" bit 544: * layout to the corresponding float. Bit 63 (the most significant) is the 545: * sign bit, bits 62-52 (masked by 0x7ff0000000000000L) represent the 546: * exponent, and bits 51-0 (masked by 0x000fffffffffffffL) are the mantissa. 547: * This function leaves NaN alone, so that you can recover the bit pattern 548: * with <code>Double.doubleToRawLongBits(double)</code>. 549: * 550: * @param bits the bits to convert 551: * @return the <code>double</code> represented by the bits 552: * @see #doubleToLongBits(double) 553: * @see #doubleToRawLongBits(double) 554: */ 555: public static double longBitsToDouble(long bits) 556: { 557: return VMDouble.longBitsToDouble(bits); 558: } 559: 560: /** 561: * Compare two Doubles numerically by comparing their <code>double</code> 562: * values. The result is positive if the first is greater, negative if the 563: * second is greater, and 0 if the two are equal. However, this special 564: * cases NaN and signed zero as follows: NaN is considered greater than 565: * all other doubles, including <code>POSITIVE_INFINITY</code>, and positive 566: * zero is considered greater than negative zero. 567: * 568: * @param d the Double to compare 569: * @return the comparison 570: * @since 1.2 571: */ 572: public int compareTo(Double d) 573: { 574: return compare(value, d.value); 575: } 576: 577: /** 578: * Behaves like <code>compareTo(Double)</code> unless the Object 579: * is not an <code>Double</code>. 580: * 581: * @param o the object to compare 582: * @return the comparison 583: * @throws ClassCastException if the argument is not a <code>Double</code> 584: * @see #compareTo(Double) 585: * @see Comparable 586: * @since 1.2 587: */ 588: public int compareTo(Object o) 589: { 590: return compare(value, ((Double) o).value); 591: } 592: 593: /** 594: * Behaves like <code>new Double(x).compareTo(new Double(y))</code>; in 595: * other words this compares two doubles, special casing NaN and zero, 596: * without the overhead of objects. 597: * 598: * @param x the first double to compare 599: * @param y the second double to compare 600: * @return the comparison 601: * @since 1.4 602: */ 603: public static int compare(double x, double y) 604: { 605: if (isNaN(x)) 606: return isNaN(y) ? 0 : 1; 607: if (isNaN(y)) 608: return -1; 609: // recall that 0.0 == -0.0, so we convert to infinites and try again 610: if (x == 0 && y == 0) 611: return (int) (1 / x - 1 / y); 612: if (x == y) 613: return 0; 614: 615: return x > y ? 1 : -1; 616: } 617: }