GNU Classpath (0.19) | ||
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: * 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 double parseDouble(String str) 256: { 257: return VMDouble.parseDouble(str); 258: } 259: 260: /** 261: * Return <code>true</code> if the <code>double</code> has the same 262: * value as <code>NaN</code>, otherwise return <code>false</code>. 263: * 264: * @param v the <code>double</code> to compare 265: * @return whether the argument is <code>NaN</code>. 266: */ 267: public static boolean isNaN(double v) 268: { 269: // This works since NaN != NaN is the only reflexive inequality 270: // comparison which returns true. 271: return v != v; 272: } 273: 274: /** 275: * Return <code>true</code> if the <code>double</code> has a value 276: * equal to either <code>NEGATIVE_INFINITY</code> or 277: * <code>POSITIVE_INFINITY</code>, otherwise return <code>false</code>. 278: * 279: * @param v the <code>double</code> to compare 280: * @return whether the argument is (-/+) infinity. 281: */ 282: public static boolean isInfinite(double v) 283: { 284: return v == POSITIVE_INFINITY || v == NEGATIVE_INFINITY; 285: } 286: 287: /** 288: * Return <code>true</code> if the value of this <code>Double</code> 289: * is the same as <code>NaN</code>, otherwise return <code>false</code>. 290: * 291: * @return whether this <code>Double</code> is <code>NaN</code> 292: */ 293: public boolean isNaN() 294: { 295: return isNaN(value); 296: } 297: 298: /** 299: * Return <code>true</code> if the value of this <code>Double</code> 300: * is the same as <code>NEGATIVE_INFINITY</code> or 301: * <code>POSITIVE_INFINITY</code>, otherwise return <code>false</code>. 302: * 303: * @return whether this <code>Double</code> is (-/+) infinity 304: */ 305: public boolean isInfinite() 306: { 307: return isInfinite(value); 308: } 309: 310: /** 311: * Convert the <code>double</code> value of this <code>Double</code> 312: * to a <code>String</code>. This method calls 313: * <code>Double.toString(double)</code> to do its dirty work. 314: * 315: * @return the <code>String</code> representation 316: * @see #toString(double) 317: */ 318: public String toString() 319: { 320: return toString(value); 321: } 322: 323: /** 324: * Return the value of this <code>Double</code> as a <code>byte</code>. 325: * 326: * @return the byte value 327: * @since 1.1 328: */ 329: public byte byteValue() 330: { 331: return (byte) value; 332: } 333: 334: /** 335: * Return the value of this <code>Double</code> as a <code>short</code>. 336: * 337: * @return the short value 338: * @since 1.1 339: */ 340: public short shortValue() 341: { 342: return (short) value; 343: } 344: 345: /** 346: * Return the value of this <code>Double</code> as an <code>int</code>. 347: * 348: * @return the int value 349: */ 350: public int intValue() 351: { 352: return (int) value; 353: } 354: 355: /** 356: * Return the value of this <code>Double</code> as a <code>long</code>. 357: * 358: * @return the long value 359: */ 360: public long longValue() 361: { 362: return (long) value; 363: } 364: 365: /** 366: * Return the value of this <code>Double</code> as a <code>float</code>. 367: * 368: * @return the float value 369: */ 370: public float floatValue() 371: { 372: return (float) value; 373: } 374: 375: /** 376: * Return the value of this <code>Double</code>. 377: * 378: * @return the double value 379: */ 380: public double doubleValue() 381: { 382: return value; 383: } 384: 385: /** 386: * Return a hashcode representing this Object. <code>Double</code>'s hash 387: * code is calculated by:<br> 388: * <code>long v = Double.doubleToLongBits(doubleValue());<br> 389: * int hash = (int)(v^(v>>32))</code>. 390: * 391: * @return this Object's hash code 392: * @see #doubleToLongBits(double) 393: */ 394: public int hashCode() 395: { 396: long v = doubleToLongBits(value); 397: return (int) (v ^ (v >>> 32)); 398: } 399: 400: /** 401: * Returns <code>true</code> if <code>obj</code> is an instance of 402: * <code>Double</code> and represents the same double value. Unlike comparing 403: * two doubles with <code>==</code>, this treats two instances of 404: * <code>Double.NaN</code> as equal, but treats <code>0.0</code> and 405: * <code>-0.0</code> as unequal. 406: * 407: * <p>Note that <code>d1.equals(d2)</code> is identical to 408: * <code>doubleToLongBits(d1.doubleValue()) == 409: * doubleToLongBits(d2.doubleValue())</code>. 410: * 411: * @param obj the object to compare 412: * @return whether the objects are semantically equal 413: */ 414: public boolean equals(Object obj) 415: { 416: if (! (obj instanceof Double)) 417: return false; 418: 419: double d = ((Double) obj).value; 420: 421: // Avoid call to native method. However, some implementations, like gcj, 422: // are better off using floatToIntBits(value) == floatToIntBits(f). 423: // Check common case first, then check NaN and 0. 424: if (value == d) 425: return (value != 0) || (1 / value == 1 / d); 426: return isNaN(value) && isNaN(d); 427: } 428: 429: /** 430: * Convert the double to the IEEE 754 floating-point "double format" bit 431: * layout. Bit 63 (the most significant) is the sign bit, bits 62-52 432: * (masked by 0x7ff0000000000000L) represent the exponent, and bits 51-0 433: * (masked by 0x000fffffffffffffL) are the mantissa. This function 434: * collapses all versions of NaN to 0x7ff8000000000000L. The result of this 435: * function can be used as the argument to 436: * <code>Double.longBitsToDouble(long)</code> to obtain the original 437: * <code>double</code> value. 438: * 439: * @param value the <code>double</code> to convert 440: * @return the bits of the <code>double</code> 441: * @see #longBitsToDouble(long) 442: */ 443: public static long doubleToLongBits(double value) 444: { 445: return VMDouble.doubleToLongBits(value); 446: } 447: 448: /** 449: * Convert the double to the IEEE 754 floating-point "double format" bit 450: * layout. Bit 63 (the most significant) is the sign bit, bits 62-52 451: * (masked by 0x7ff0000000000000L) represent the exponent, and bits 51-0 452: * (masked by 0x000fffffffffffffL) are the mantissa. This function 453: * leaves NaN alone, rather than collapsing to a canonical value. The 454: * result of this function can be used as the argument to 455: * <code>Double.longBitsToDouble(long)</code> to obtain the original 456: * <code>double</code> value. 457: * 458: * @param value the <code>double</code> to convert 459: * @return the bits of the <code>double</code> 460: * @see #longBitsToDouble(long) 461: */ 462: public static long doubleToRawLongBits(double value) 463: { 464: return VMDouble.doubleToRawLongBits(value); 465: } 466: 467: /** 468: * Convert the argument in IEEE 754 floating-point "double format" bit 469: * layout to the corresponding float. Bit 63 (the most significant) is the 470: * sign bit, bits 62-52 (masked by 0x7ff0000000000000L) represent the 471: * exponent, and bits 51-0 (masked by 0x000fffffffffffffL) are the mantissa. 472: * This function leaves NaN alone, so that you can recover the bit pattern 473: * with <code>Double.doubleToRawLongBits(double)</code>. 474: * 475: * @param bits the bits to convert 476: * @return the <code>double</code> represented by the bits 477: * @see #doubleToLongBits(double) 478: * @see #doubleToRawLongBits(double) 479: */ 480: public static double longBitsToDouble(long bits) 481: { 482: return VMDouble.longBitsToDouble(bits); 483: } 484: 485: /** 486: * Compare two Doubles numerically by comparing their <code>double</code> 487: * values. The result is positive if the first is greater, negative if the 488: * second is greater, and 0 if the two are equal. However, this special 489: * cases NaN and signed zero as follows: NaN is considered greater than 490: * all other doubles, including <code>POSITIVE_INFINITY</code>, and positive 491: * zero is considered greater than negative zero. 492: * 493: * @param d the Double to compare 494: * @return the comparison 495: * @since 1.2 496: */ 497: public int compareTo(Double d) 498: { 499: return compare(value, d.value); 500: } 501: 502: /** 503: * Behaves like <code>compareTo(Double)</code> unless the Object 504: * is not an <code>Double</code>. 505: * 506: * @param o the object to compare 507: * @return the comparison 508: * @throws ClassCastException if the argument is not a <code>Double</code> 509: * @see #compareTo(Double) 510: * @see Comparable 511: * @since 1.2 512: */ 513: public int compareTo(Object o) 514: { 515: return compare(value, ((Double) o).value); 516: } 517: 518: /** 519: * Behaves like <code>new Double(x).compareTo(new Double(y))</code>; in 520: * other words this compares two doubles, special casing NaN and zero, 521: * without the overhead of objects. 522: * 523: * @param x the first double to compare 524: * @param y the second double to compare 525: * @return the comparison 526: * @since 1.4 527: */ 528: public static int compare(double x, double y) 529: { 530: if (isNaN(x)) 531: return isNaN(y) ? 0 : 1; 532: if (isNaN(y)) 533: return -1; 534: // recall that 0.0 == -0.0, so we convert to infinites and try again 535: if (x == 0 && y == 0) 536: return (int) (1 / x - 1 / y); 537: if (x == y) 538: return 0; 539: 540: return x > y ? 1 : -1; 541: } 542: }
GNU Classpath (0.19) |