GNU Classpath (0.95) | |
Frames | No Frames |
1: /* java.lang.Math -- common mathematical functions, native allowed (VMMath) 2: Copyright (C) 1998, 2001, 2002, 2003, 2006 Free Software Foundation, Inc. 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: 39: package java.lang; 40: 41: import gnu.classpath.Configuration; 42: 43: import java.util.Random; 44: 45: /** 46: * Helper class containing useful mathematical functions and constants. 47: * <P> 48: * 49: * Note that angles are specified in radians. Conversion functions are 50: * provided for your convenience. 51: * 52: * @author Paul Fisher 53: * @author John Keiser 54: * @author Eric Blake (ebb9@email.byu.edu) 55: * @author Andrew John Hughes (gnu_andrew@member.fsf.org) 56: * @since 1.0 57: */ 58: public final class Math 59: { 60: 61: // FIXME - This is here because we need to load the "javalang" system 62: // library somewhere late in the bootstrap cycle. We cannot do this 63: // from VMSystem or VMRuntime since those are used to actually load 64: // the library. This is mainly here because historically Math was 65: // late enough in the bootstrap cycle to start using System after it 66: // was initialized (called from the java.util classes). 67: static 68: { 69: if (Configuration.INIT_LOAD_LIBRARY) 70: { 71: System.loadLibrary("javalang"); 72: } 73: } 74: 75: /** 76: * Math is non-instantiable 77: */ 78: private Math() 79: { 80: } 81: 82: /** 83: * A random number generator, initialized on first use. 84: */ 85: private static Random rand; 86: 87: /** 88: * The most accurate approximation to the mathematical constant <em>e</em>: 89: * <code>2.718281828459045</code>. Used in natural log and exp. 90: * 91: * @see #log(double) 92: * @see #exp(double) 93: */ 94: public static final double E = 2.718281828459045; 95: 96: /** 97: * The most accurate approximation to the mathematical constant <em>pi</em>: 98: * <code>3.141592653589793</code>. This is the ratio of a circle's diameter 99: * to its circumference. 100: */ 101: public static final double PI = 3.141592653589793; 102: 103: /** 104: * Take the absolute value of the argument. 105: * (Absolute value means make it positive.) 106: * <P> 107: * 108: * Note that the the largest negative value (Integer.MIN_VALUE) cannot 109: * be made positive. In this case, because of the rules of negation in 110: * a computer, MIN_VALUE is what will be returned. 111: * This is a <em>negative</em> value. You have been warned. 112: * 113: * @param i the number to take the absolute value of 114: * @return the absolute value 115: * @see Integer#MIN_VALUE 116: */ 117: public static int abs(int i) 118: { 119: return (i < 0) ? -i : i; 120: } 121: 122: /** 123: * Take the absolute value of the argument. 124: * (Absolute value means make it positive.) 125: * <P> 126: * 127: * Note that the the largest negative value (Long.MIN_VALUE) cannot 128: * be made positive. In this case, because of the rules of negation in 129: * a computer, MIN_VALUE is what will be returned. 130: * This is a <em>negative</em> value. You have been warned. 131: * 132: * @param l the number to take the absolute value of 133: * @return the absolute value 134: * @see Long#MIN_VALUE 135: */ 136: public static long abs(long l) 137: { 138: return (l < 0) ? -l : l; 139: } 140: 141: /** 142: * Take the absolute value of the argument. 143: * (Absolute value means make it positive.) 144: * <P> 145: * 146: * This is equivalent, but faster than, calling 147: * <code>Float.intBitsToFloat(0x7fffffff & Float.floatToIntBits(a))</code>. 148: * 149: * @param f the number to take the absolute value of 150: * @return the absolute value 151: */ 152: public static float abs(float f) 153: { 154: return (f <= 0) ? 0 - f : f; 155: } 156: 157: /** 158: * Take the absolute value of the argument. 159: * (Absolute value means make it positive.) 160: * 161: * This is equivalent, but faster than, calling 162: * <code>Double.longBitsToDouble(Double.doubleToLongBits(a) 163: * << 1) >>> 1);</code>. 164: * 165: * @param d the number to take the absolute value of 166: * @return the absolute value 167: */ 168: public static double abs(double d) 169: { 170: return (d <= 0) ? 0 - d : d; 171: } 172: 173: /** 174: * Return whichever argument is smaller. 175: * 176: * @param a the first number 177: * @param b a second number 178: * @return the smaller of the two numbers 179: */ 180: public static int min(int a, int b) 181: { 182: return (a < b) ? a : b; 183: } 184: 185: /** 186: * Return whichever argument is smaller. 187: * 188: * @param a the first number 189: * @param b a second number 190: * @return the smaller of the two numbers 191: */ 192: public static long min(long a, long b) 193: { 194: return (a < b) ? a : b; 195: } 196: 197: /** 198: * Return whichever argument is smaller. If either argument is NaN, the 199: * result is NaN, and when comparing 0 and -0, -0 is always smaller. 200: * 201: * @param a the first number 202: * @param b a second number 203: * @return the smaller of the two numbers 204: */ 205: public static float min(float a, float b) 206: { 207: // this check for NaN, from JLS 15.21.1, saves a method call 208: if (a != a) 209: return a; 210: // no need to check if b is NaN; < will work correctly 211: // recall that -0.0 == 0.0, but [+-]0.0 - [+-]0.0 behaves special 212: if (a == 0 && b == 0) 213: return -(-a - b); 214: return (a < b) ? a : b; 215: } 216: 217: /** 218: * Return whichever argument is smaller. If either argument is NaN, the 219: * result is NaN, and when comparing 0 and -0, -0 is always smaller. 220: * 221: * @param a the first number 222: * @param b a second number 223: * @return the smaller of the two numbers 224: */ 225: public static double min(double a, double b) 226: { 227: // this check for NaN, from JLS 15.21.1, saves a method call 228: if (a != a) 229: return a; 230: // no need to check if b is NaN; < will work correctly 231: // recall that -0.0 == 0.0, but [+-]0.0 - [+-]0.0 behaves special 232: if (a == 0 && b == 0) 233: return -(-a - b); 234: return (a < b) ? a : b; 235: } 236: 237: /** 238: * Return whichever argument is larger. 239: * 240: * @param a the first number 241: * @param b a second number 242: * @return the larger of the two numbers 243: */ 244: public static int max(int a, int b) 245: { 246: return (a > b) ? a : b; 247: } 248: 249: /** 250: * Return whichever argument is larger. 251: * 252: * @param a the first number 253: * @param b a second number 254: * @return the larger of the two numbers 255: */ 256: public static long max(long a, long b) 257: { 258: return (a > b) ? a : b; 259: } 260: 261: /** 262: * Return whichever argument is larger. If either argument is NaN, the 263: * result is NaN, and when comparing 0 and -0, 0 is always larger. 264: * 265: * @param a the first number 266: * @param b a second number 267: * @return the larger of the two numbers 268: */ 269: public static float max(float a, float b) 270: { 271: // this check for NaN, from JLS 15.21.1, saves a method call 272: if (a != a) 273: return a; 274: // no need to check if b is NaN; > will work correctly 275: // recall that -0.0 == 0.0, but [+-]0.0 - [+-]0.0 behaves special 276: if (a == 0 && b == 0) 277: return a - -b; 278: return (a > b) ? a : b; 279: } 280: 281: /** 282: * Return whichever argument is larger. If either argument is NaN, the 283: * result is NaN, and when comparing 0 and -0, 0 is always larger. 284: * 285: * @param a the first number 286: * @param b a second number 287: * @return the larger of the two numbers 288: */ 289: public static double max(double a, double b) 290: { 291: // this check for NaN, from JLS 15.21.1, saves a method call 292: if (a != a) 293: return a; 294: // no need to check if b is NaN; > will work correctly 295: // recall that -0.0 == 0.0, but [+-]0.0 - [+-]0.0 behaves special 296: if (a == 0 && b == 0) 297: return a - -b; 298: return (a > b) ? a : b; 299: } 300: 301: /** 302: * The trigonometric function <em>sin</em>. The sine of NaN or infinity is 303: * NaN, and the sine of 0 retains its sign. This is accurate within 1 ulp, 304: * and is semi-monotonic. 305: * 306: * @param a the angle (in radians) 307: * @return sin(a) 308: */ 309: public static double sin(double a) 310: { 311: return VMMath.sin(a); 312: } 313: 314: /** 315: * The trigonometric function <em>cos</em>. The cosine of NaN or infinity is 316: * NaN. This is accurate within 1 ulp, and is semi-monotonic. 317: * 318: * @param a the angle (in radians) 319: * @return cos(a) 320: */ 321: public static double cos(double a) 322: { 323: return VMMath.cos(a); 324: } 325: 326: /** 327: * The trigonometric function <em>tan</em>. The tangent of NaN or infinity 328: * is NaN, and the tangent of 0 retains its sign. This is accurate within 1 329: * ulp, and is semi-monotonic. 330: * 331: * @param a the angle (in radians) 332: * @return tan(a) 333: */ 334: public static double tan(double a) 335: { 336: return VMMath.tan(a); 337: } 338: 339: /** 340: * The trigonometric function <em>arcsin</em>. The range of angles returned 341: * is -pi/2 to pi/2 radians (-90 to 90 degrees). If the argument is NaN or 342: * its absolute value is beyond 1, the result is NaN; and the arcsine of 343: * 0 retains its sign. This is accurate within 1 ulp, and is semi-monotonic. 344: * 345: * @param a the sin to turn back into an angle 346: * @return arcsin(a) 347: */ 348: public static double asin(double a) 349: { 350: return VMMath.asin(a); 351: } 352: 353: /** 354: * The trigonometric function <em>arccos</em>. The range of angles returned 355: * is 0 to pi radians (0 to 180 degrees). If the argument is NaN or 356: * its absolute value is beyond 1, the result is NaN. This is accurate 357: * within 1 ulp, and is semi-monotonic. 358: * 359: * @param a the cos to turn back into an angle 360: * @return arccos(a) 361: */ 362: public static double acos(double a) 363: { 364: return VMMath.acos(a); 365: } 366: 367: /** 368: * The trigonometric function <em>arcsin</em>. The range of angles returned 369: * is -pi/2 to pi/2 radians (-90 to 90 degrees). If the argument is NaN, the 370: * result is NaN; and the arctangent of 0 retains its sign. This is accurate 371: * within 1 ulp, and is semi-monotonic. 372: * 373: * @param a the tan to turn back into an angle 374: * @return arcsin(a) 375: * @see #atan2(double, double) 376: */ 377: public static double atan(double a) 378: { 379: return VMMath.atan(a); 380: } 381: 382: /** 383: * A special version of the trigonometric function <em>arctan</em>, for 384: * converting rectangular coordinates <em>(x, y)</em> to polar 385: * <em>(r, theta)</em>. This computes the arctangent of x/y in the range 386: * of -pi to pi radians (-180 to 180 degrees). Special cases:<ul> 387: * <li>If either argument is NaN, the result is NaN.</li> 388: * <li>If the first argument is positive zero and the second argument is 389: * positive, or the first argument is positive and finite and the second 390: * argument is positive infinity, then the result is positive zero.</li> 391: * <li>If the first argument is negative zero and the second argument is 392: * positive, or the first argument is negative and finite and the second 393: * argument is positive infinity, then the result is negative zero.</li> 394: * <li>If the first argument is positive zero and the second argument is 395: * negative, or the first argument is positive and finite and the second 396: * argument is negative infinity, then the result is the double value 397: * closest to pi.</li> 398: * <li>If the first argument is negative zero and the second argument is 399: * negative, or the first argument is negative and finite and the second 400: * argument is negative infinity, then the result is the double value 401: * closest to -pi.</li> 402: * <li>If the first argument is positive and the second argument is 403: * positive zero or negative zero, or the first argument is positive 404: * infinity and the second argument is finite, then the result is the 405: * double value closest to pi/2.</li> 406: * <li>If the first argument is negative and the second argument is 407: * positive zero or negative zero, or the first argument is negative 408: * infinity and the second argument is finite, then the result is the 409: * double value closest to -pi/2.</li> 410: * <li>If both arguments are positive infinity, then the result is the 411: * double value closest to pi/4.</li> 412: * <li>If the first argument is positive infinity and the second argument 413: * is negative infinity, then the result is the double value closest to 414: * 3*pi/4.</li> 415: * <li>If the first argument is negative infinity and the second argument 416: * is positive infinity, then the result is the double value closest to 417: * -pi/4.</li> 418: * <li>If both arguments are negative infinity, then the result is the 419: * double value closest to -3*pi/4.</li> 420: * 421: * </ul><p>This is accurate within 2 ulps, and is semi-monotonic. To get r, 422: * use sqrt(x*x+y*y). 423: * 424: * @param y the y position 425: * @param x the x position 426: * @return <em>theta</em> in the conversion of (x, y) to (r, theta) 427: * @see #atan(double) 428: */ 429: public static double atan2(double y, double x) 430: { 431: return VMMath.atan2(y,x); 432: } 433: 434: /** 435: * Take <em>e</em><sup>a</sup>. The opposite of <code>log()</code>. If the 436: * argument is NaN, the result is NaN; if the argument is positive infinity, 437: * the result is positive infinity; and if the argument is negative 438: * infinity, the result is positive zero. This is accurate within 1 ulp, 439: * and is semi-monotonic. 440: * 441: * @param a the number to raise to the power 442: * @return the number raised to the power of <em>e</em> 443: * @see #log(double) 444: * @see #pow(double, double) 445: */ 446: public static double exp(double a) 447: { 448: return VMMath.exp(a); 449: } 450: 451: /** 452: * Take ln(a) (the natural log). The opposite of <code>exp()</code>. If the 453: * argument is NaN or negative, the result is NaN; if the argument is 454: * positive infinity, the result is positive infinity; and if the argument 455: * is either zero, the result is negative infinity. This is accurate within 456: * 1 ulp, and is semi-monotonic. 457: * 458: * <p>Note that the way to get log<sub>b</sub>(a) is to do this: 459: * <code>ln(a) / ln(b)</code>. 460: * 461: * @param a the number to take the natural log of 462: * @return the natural log of <code>a</code> 463: * @see #exp(double) 464: */ 465: public static double log(double a) 466: { 467: return VMMath.log(a); 468: } 469: 470: /** 471: * Take a square root. If the argument is NaN or negative, the result is 472: * NaN; if the argument is positive infinity, the result is positive 473: * infinity; and if the result is either zero, the result is the same. 474: * This is accurate within the limits of doubles. 475: * 476: * <p>For a cube root, use <code>cbrt</code>. For other roots, use 477: * <code>pow(a, 1 / rootNumber)</code>.</p> 478: * 479: * @param a the numeric argument 480: * @return the square root of the argument 481: * @see #cbrt(double) 482: * @see #pow(double, double) 483: */ 484: public static double sqrt(double a) 485: { 486: return VMMath.sqrt(a); 487: } 488: 489: /** 490: * Raise a number to a power. Special cases:<ul> 491: * <li>If the second argument is positive or negative zero, then the result 492: * is 1.0.</li> 493: * <li>If the second argument is 1.0, then the result is the same as the 494: * first argument.</li> 495: * <li>If the second argument is NaN, then the result is NaN.</li> 496: * <li>If the first argument is NaN and the second argument is nonzero, 497: * then the result is NaN.</li> 498: * <li>If the absolute value of the first argument is greater than 1 and 499: * the second argument is positive infinity, or the absolute value of the 500: * first argument is less than 1 and the second argument is negative 501: * infinity, then the result is positive infinity.</li> 502: * <li>If the absolute value of the first argument is greater than 1 and 503: * the second argument is negative infinity, or the absolute value of the 504: * first argument is less than 1 and the second argument is positive 505: * infinity, then the result is positive zero.</li> 506: * <li>If the absolute value of the first argument equals 1 and the second 507: * argument is infinite, then the result is NaN.</li> 508: * <li>If the first argument is positive zero and the second argument is 509: * greater than zero, or the first argument is positive infinity and the 510: * second argument is less than zero, then the result is positive zero.</li> 511: * <li>If the first argument is positive zero and the second argument is 512: * less than zero, or the first argument is positive infinity and the 513: * second argument is greater than zero, then the result is positive 514: * infinity.</li> 515: * <li>If the first argument is negative zero and the second argument is 516: * greater than zero but not a finite odd integer, or the first argument is 517: * negative infinity and the second argument is less than zero but not a 518: * finite odd integer, then the result is positive zero.</li> 519: * <li>If the first argument is negative zero and the second argument is a 520: * positive finite odd integer, or the first argument is negative infinity 521: * and the second argument is a negative finite odd integer, then the result 522: * is negative zero.</li> 523: * <li>If the first argument is negative zero and the second argument is 524: * less than zero but not a finite odd integer, or the first argument is 525: * negative infinity and the second argument is greater than zero but not a 526: * finite odd integer, then the result is positive infinity.</li> 527: * <li>If the first argument is negative zero and the second argument is a 528: * negative finite odd integer, or the first argument is negative infinity 529: * and the second argument is a positive finite odd integer, then the result 530: * is negative infinity.</li> 531: * <li>If the first argument is less than zero and the second argument is a 532: * finite even integer, then the result is equal to the result of raising 533: * the absolute value of the first argument to the power of the second 534: * argument.</li> 535: * <li>If the first argument is less than zero and the second argument is a 536: * finite odd integer, then the result is equal to the negative of the 537: * result of raising the absolute value of the first argument to the power 538: * of the second argument.</li> 539: * <li>If the first argument is finite and less than zero and the second 540: * argument is finite and not an integer, then the result is NaN.</li> 541: * <li>If both arguments are integers, then the result is exactly equal to 542: * the mathematical result of raising the first argument to the power of 543: * the second argument if that result can in fact be represented exactly as 544: * a double value.</li> 545: * 546: * </ul><p>(In the foregoing descriptions, a floating-point value is 547: * considered to be an integer if and only if it is a fixed point of the 548: * method {@link #ceil(double)} or, equivalently, a fixed point of the 549: * method {@link #floor(double)}. A value is a fixed point of a one-argument 550: * method if and only if the result of applying the method to the value is 551: * equal to the value.) This is accurate within 1 ulp, and is semi-monotonic. 552: * 553: * @param a the number to raise 554: * @param b the power to raise it to 555: * @return a<sup>b</sup> 556: */ 557: public static double pow(double a, double b) 558: { 559: return VMMath.pow(a,b); 560: } 561: 562: /** 563: * Get the IEEE 754 floating point remainder on two numbers. This is the 564: * value of <code>x - y * <em>n</em></code>, where <em>n</em> is the closest 565: * double to <code>x / y</code> (ties go to the even n); for a zero 566: * remainder, the sign is that of <code>x</code>. If either argument is NaN, 567: * the first argument is infinite, or the second argument is zero, the result 568: * is NaN; if x is finite but y is infinite, the result is x. This is 569: * accurate within the limits of doubles. 570: * 571: * @param x the dividend (the top half) 572: * @param y the divisor (the bottom half) 573: * @return the IEEE 754-defined floating point remainder of x/y 574: * @see #rint(double) 575: */ 576: public static double IEEEremainder(double x, double y) 577: { 578: return VMMath.IEEEremainder(x,y); 579: } 580: 581: /** 582: * Take the nearest integer that is that is greater than or equal to the 583: * argument. If the argument is NaN, infinite, or zero, the result is the 584: * same; if the argument is between -1 and 0, the result is negative zero. 585: * Note that <code>Math.ceil(x) == -Math.floor(-x)</code>. 586: * 587: * @param a the value to act upon 588: * @return the nearest integer >= <code>a</code> 589: */ 590: public static double ceil(double a) 591: { 592: return VMMath.ceil(a); 593: } 594: 595: /** 596: * Take the nearest integer that is that is less than or equal to the 597: * argument. If the argument is NaN, infinite, or zero, the result is the 598: * same. Note that <code>Math.ceil(x) == -Math.floor(-x)</code>. 599: * 600: * @param a the value to act upon 601: * @return the nearest integer <= <code>a</code> 602: */ 603: public static double floor(double a) 604: { 605: return VMMath.floor(a); 606: } 607: 608: /** 609: * Take the nearest integer to the argument. If it is exactly between 610: * two integers, the even integer is taken. If the argument is NaN, 611: * infinite, or zero, the result is the same. 612: * 613: * @param a the value to act upon 614: * @return the nearest integer to <code>a</code> 615: */ 616: public static double rint(double a) 617: { 618: return VMMath.rint(a); 619: } 620: 621: /** 622: * Take the nearest integer to the argument. This is equivalent to 623: * <code>(int) Math.floor(a + 0.5f)</code>. If the argument is NaN, the result 624: * is 0; otherwise if the argument is outside the range of int, the result 625: * will be Integer.MIN_VALUE or Integer.MAX_VALUE, as appropriate. 626: * 627: * @param a the argument to round 628: * @return the nearest integer to the argument 629: * @see Integer#MIN_VALUE 630: * @see Integer#MAX_VALUE 631: */ 632: public static int round(float a) 633: { 634: // this check for NaN, from JLS 15.21.1, saves a method call 635: if (a != a) 636: return 0; 637: return (int) floor(a + 0.5f); 638: } 639: 640: /** 641: * Take the nearest long to the argument. This is equivalent to 642: * <code>(long) Math.floor(a + 0.5)</code>. If the argument is NaN, the 643: * result is 0; otherwise if the argument is outside the range of long, the 644: * result will be Long.MIN_VALUE or Long.MAX_VALUE, as appropriate. 645: * 646: * @param a the argument to round 647: * @return the nearest long to the argument 648: * @see Long#MIN_VALUE 649: * @see Long#MAX_VALUE 650: */ 651: public static long round(double a) 652: { 653: // this check for NaN, from JLS 15.21.1, saves a method call 654: if (a != a) 655: return 0; 656: return (long) floor(a + 0.5d); 657: } 658: 659: /** 660: * Get a random number. This behaves like Random.nextDouble(), seeded by 661: * System.currentTimeMillis() when first called. In other words, the number 662: * is from a pseudorandom sequence, and lies in the range [+0.0, 1.0). 663: * This random sequence is only used by this method, and is threadsafe, 664: * although you may want your own random number generator if it is shared 665: * among threads. 666: * 667: * @return a random number 668: * @see Random#nextDouble() 669: * @see System#currentTimeMillis() 670: */ 671: public static synchronized double random() 672: { 673: if (rand == null) 674: rand = new Random(); 675: return rand.nextDouble(); 676: } 677: 678: /** 679: * Convert from degrees to radians. The formula for this is 680: * radians = degrees * (pi/180); however it is not always exact given the 681: * limitations of floating point numbers. 682: * 683: * @param degrees an angle in degrees 684: * @return the angle in radians 685: * @since 1.2 686: */ 687: public static double toRadians(double degrees) 688: { 689: return (degrees * PI) / 180; 690: } 691: 692: /** 693: * Convert from radians to degrees. The formula for this is 694: * degrees = radians * (180/pi); however it is not always exact given the 695: * limitations of floating point numbers. 696: * 697: * @param rads an angle in radians 698: * @return the angle in degrees 699: * @since 1.2 700: */ 701: public static double toDegrees(double rads) 702: { 703: return (rads * 180) / PI; 704: } 705: 706: /** 707: * <p> 708: * Take a cube root. If the argument is <code>NaN</code>, an infinity or 709: * zero, then the original value is returned. The returned result is 710: * within 1 ulp of the exact result. For a finite value, <code>x</code>, 711: * the cube root of <code>-x</code> is equal to the negation of the cube root 712: * of <code>x</code>. 713: * </p> 714: * <p> 715: * For a square root, use <code>sqrt</code>. For other roots, use 716: * <code>pow(a, 1 / rootNumber)</code>. 717: * </p> 718: * 719: * @param a the numeric argument 720: * @return the cube root of the argument 721: * @see #sqrt(double) 722: * @see #pow(double, double) 723: * @since 1.5 724: */ 725: public static double cbrt(double a) 726: { 727: return VMMath.cbrt(a); 728: } 729: 730: /** 731: * <p> 732: * Returns the hyperbolic cosine of the given value. For a value, 733: * <code>x</code>, the hyperbolic cosine is <code>(e<sup>x</sup> + 734: * e<sup>-x</sup>)/2</code> 735: * with <code>e</code> being <a href="#E">Euler's number</a>. The returned 736: * result is within 2.5 ulps of the exact result. 737: * </p> 738: * <p> 739: * If the supplied value is <code>NaN</code>, then the original value is 740: * returned. For either infinity, positive infinity is returned. 741: * The hyperbolic cosine of zero is 1.0. 742: * </p> 743: * 744: * @param a the numeric argument 745: * @return the hyperbolic cosine of <code>a</code>. 746: * @since 1.5 747: */ 748: public static double cosh(double a) 749: { 750: return VMMath.cosh(a); 751: } 752: 753: /** 754: * <p> 755: * Returns <code>e<sup>a</sup> - 1. For values close to 0, the 756: * result of <code>expm1(a) + 1</code> tend to be much closer to the 757: * exact result than simply <code>exp(x)</code>. The result is within 758: * 1 ulp of the exact result, and results are semi-monotonic. For finite 759: * inputs, the returned value is greater than or equal to -1.0. Once 760: * a result enters within half a ulp of this limit, the limit is returned. 761: * </p> 762: * <p> 763: * For <code>NaN</code>, positive infinity and zero, the original value 764: * is returned. Negative infinity returns a result of -1.0 (the limit). 765: * </p> 766: * 767: * @param a the numeric argument 768: * @return <code>e<sup>a</sup> - 1</code> 769: * @since 1.5 770: */ 771: public static double expm1(double a) 772: { 773: return VMMath.expm1(a); 774: } 775: 776: /** 777: * <p> 778: * Returns the hypotenuse, <code>a<sup>2</sup> + b<sup>2</sup></code>, 779: * without intermediate overflow or underflow. The returned result is 780: * within 1 ulp of the exact result. If one parameter is held constant, 781: * then the result in the other parameter is semi-monotonic. 782: * </p> 783: * <p> 784: * If either of the arguments is an infinity, then the returned result 785: * is positive infinity. Otherwise, if either argument is <code>NaN</code>, 786: * then <code>NaN</code> is returned. 787: * </p> 788: * 789: * @param a the first parameter. 790: * @param b the second parameter. 791: * @return the hypotenuse matching the supplied parameters. 792: * @since 1.5 793: */ 794: public static double hypot(double a, double b) 795: { 796: return VMMath.hypot(a,b); 797: } 798: 799: /** 800: * <p> 801: * Returns the base 10 logarithm of the supplied value. The returned 802: * result is within 1 ulp of the exact result, and the results are 803: * semi-monotonic. 804: * </p> 805: * <p> 806: * Arguments of either <code>NaN</code> or less than zero return 807: * <code>NaN</code>. An argument of positive infinity returns positive 808: * infinity. Negative infinity is returned if either positive or negative 809: * zero is supplied. Where the argument is the result of 810: * <code>10<sup>n</sup</code>, then <code>n</code> is returned. 811: * </p> 812: * 813: * @param a the numeric argument. 814: * @return the base 10 logarithm of <code>a</code>. 815: * @since 1.5 816: */ 817: public static double log10(double a) 818: { 819: return VMMath.log10(a); 820: } 821: 822: /** 823: * <p> 824: * Returns the natural logarithm resulting from the sum of the argument, 825: * <code>a</code> and 1. For values close to 0, the 826: * result of <code>log1p(a)</code> tend to be much closer to the 827: * exact result than simply <code>log(1.0+a)</code>. The returned 828: * result is within 1 ulp of the exact result, and the results are 829: * semi-monotonic. 830: * </p> 831: * <p> 832: * Arguments of either <code>NaN</code> or less than -1 return 833: * <code>NaN</code>. An argument of positive infinity or zero 834: * returns the original argument. Negative infinity is returned from an 835: * argument of -1. 836: * </p> 837: * 838: * @param a the numeric argument. 839: * @return the natural logarithm of <code>a</code> + 1. 840: * @since 1.5 841: */ 842: public static double log1p(double a) 843: { 844: return VMMath.log1p(a); 845: } 846: 847: /** 848: * <p> 849: * Returns the sign of the argument as follows: 850: * </p> 851: * <ul> 852: * <li>If <code>a</code> is greater than zero, the result is 1.0.</li> 853: * <li>If <code>a</code> is less than zero, the result is -1.0.</li> 854: * <li>If <code>a</code> is <code>NaN</code>, the result is <code>NaN</code>. 855: * <li>If <code>a</code> is positive or negative zero, the result is the 856: * same.</li> 857: * </ul> 858: * 859: * @param a the numeric argument. 860: * @return the sign of the argument. 861: * @since 1.5. 862: */ 863: public static double signum(double a) 864: { 865: if (Double.isNaN(a)) 866: return Double.NaN; 867: if (a > 0) 868: return 1.0; 869: if (a < 0) 870: return -1.0; 871: return a; 872: } 873: 874: /** 875: * <p> 876: * Returns the sign of the argument as follows: 877: * </p> 878: * <ul> 879: * <li>If <code>a</code> is greater than zero, the result is 1.0f.</li> 880: * <li>If <code>a</code> is less than zero, the result is -1.0f.</li> 881: * <li>If <code>a</code> is <code>NaN</code>, the result is <code>NaN</code>. 882: * <li>If <code>a</code> is positive or negative zero, the result is the 883: * same.</li> 884: * </ul> 885: * 886: * @param a the numeric argument. 887: * @return the sign of the argument. 888: * @since 1.5. 889: */ 890: public static float signum(float a) 891: { 892: if (Float.isNaN(a)) 893: return Float.NaN; 894: if (a > 0) 895: return 1.0f; 896: if (a < 0) 897: return -1.0f; 898: return a; 899: } 900: 901: /** 902: * <p> 903: * Returns the hyperbolic sine of the given value. For a value, 904: * <code>x</code>, the hyperbolic sine is <code>(e<sup>x</sup> - 905: * e<sup>-x</sup>)/2</code> 906: * with <code>e</code> being <a href="#E">Euler's number</a>. The returned 907: * result is within 2.5 ulps of the exact result. 908: * </p> 909: * <p> 910: * If the supplied value is <code>NaN</code>, an infinity or a zero, then the 911: * original value is returned. 912: * </p> 913: * 914: * @param a the numeric argument 915: * @return the hyperbolic sine of <code>a</code>. 916: * @since 1.5 917: */ 918: public static double sinh(double a) 919: { 920: return VMMath.sinh(a); 921: } 922: 923: /** 924: * <p> 925: * Returns the hyperbolic tangent of the given value. For a value, 926: * <code>x</code>, the hyperbolic tangent is <code>(e<sup>x</sup> - 927: * e<sup>-x</sup>)/(e<sup>x</sup> + e<sup>-x</sup>)</code> 928: * (i.e. <code>sinh(a)/cosh(a)</code>) 929: * with <code>e</code> being <a href="#E">Euler's number</a>. The returned 930: * result is within 2.5 ulps of the exact result. The absolute value 931: * of the exact result is always less than 1. Computed results are thus 932: * less than or equal to 1 for finite arguments, with results within 933: * half a ulp of either positive or negative 1 returning the appropriate 934: * limit value (i.e. as if the argument was an infinity). 935: * </p> 936: * <p> 937: * If the supplied value is <code>NaN</code> or zero, then the original 938: * value is returned. Positive infinity returns +1.0 and negative infinity 939: * returns -1.0. 940: * </p> 941: * 942: * @param a the numeric argument 943: * @return the hyperbolic tangent of <code>a</code>. 944: * @since 1.5 945: */ 946: public static double tanh(double a) 947: { 948: return VMMath.tanh(a); 949: } 950: 951: /** 952: * Return the ulp for the given double argument. The ulp is the 953: * difference between the argument and the next larger double. Note 954: * that the sign of the double argument is ignored, that is, 955: * ulp(x) == ulp(-x). If the argument is a NaN, then NaN is returned. 956: * If the argument is an infinity, then +Inf is returned. If the 957: * argument is zero (either positive or negative), then 958: * {@link Double#MIN_VALUE} is returned. 959: * @param d the double whose ulp should be returned 960: * @return the difference between the argument and the next larger double 961: * @since 1.5 962: */ 963: public static double ulp(double d) 964: { 965: if (Double.isNaN(d)) 966: return d; 967: if (Double.isInfinite(d)) 968: return Double.POSITIVE_INFINITY; 969: // This handles both +0.0 and -0.0. 970: if (d == 0.0) 971: return Double.MIN_VALUE; 972: long bits = Double.doubleToLongBits(d); 973: final int mantissaBits = 52; 974: final int exponentBits = 11; 975: final long mantMask = (1L << mantissaBits) - 1; 976: long mantissa = bits & mantMask; 977: final long expMask = (1L << exponentBits) - 1; 978: long exponent = (bits >>> mantissaBits) & expMask; 979: 980: // Denormal number, so the answer is easy. 981: if (exponent == 0) 982: { 983: long result = (exponent << mantissaBits) | 1L; 984: return Double.longBitsToDouble(result); 985: } 986: 987: // Conceptually we want to have '1' as the mantissa. Then we would 988: // shift the mantissa over to make a normal number. If this underflows 989: // the exponent, we will make a denormal result. 990: long newExponent = exponent - mantissaBits; 991: long newMantissa; 992: if (newExponent > 0) 993: newMantissa = 0; 994: else 995: { 996: newMantissa = 1L << -(newExponent - 1); 997: newExponent = 0; 998: } 999: return Double.longBitsToDouble((newExponent << mantissaBits) | newMantissa); 1000: } 1001: 1002: /** 1003: * Return the ulp for the given float argument. The ulp is the 1004: * difference between the argument and the next larger float. Note 1005: * that the sign of the float argument is ignored, that is, 1006: * ulp(x) == ulp(-x). If the argument is a NaN, then NaN is returned. 1007: * If the argument is an infinity, then +Inf is returned. If the 1008: * argument is zero (either positive or negative), then 1009: * {@link Float#MIN_VALUE} is returned. 1010: * @param f the float whose ulp should be returned 1011: * @return the difference between the argument and the next larger float 1012: * @since 1.5 1013: */ 1014: public static float ulp(float f) 1015: { 1016: if (Float.isNaN(f)) 1017: return f; 1018: if (Float.isInfinite(f)) 1019: return Float.POSITIVE_INFINITY; 1020: // This handles both +0.0 and -0.0. 1021: if (f == 0.0) 1022: return Float.MIN_VALUE; 1023: int bits = Float.floatToIntBits(f); 1024: final int mantissaBits = 23; 1025: final int exponentBits = 8; 1026: final int mantMask = (1 << mantissaBits) - 1; 1027: int mantissa = bits & mantMask; 1028: final int expMask = (1 << exponentBits) - 1; 1029: int exponent = (bits >>> mantissaBits) & expMask; 1030: 1031: // Denormal number, so the answer is easy. 1032: if (exponent == 0) 1033: { 1034: int result = (exponent << mantissaBits) | 1; 1035: return Float.intBitsToFloat(result); 1036: } 1037: 1038: // Conceptually we want to have '1' as the mantissa. Then we would 1039: // shift the mantissa over to make a normal number. If this underflows 1040: // the exponent, we will make a denormal result. 1041: int newExponent = exponent - mantissaBits; 1042: int newMantissa; 1043: if (newExponent > 0) 1044: newMantissa = 0; 1045: else 1046: { 1047: newMantissa = 1 << -(newExponent - 1); 1048: newExponent = 0; 1049: } 1050: return Float.intBitsToFloat((newExponent << mantissaBits) | newMantissa); 1051: } 1052: }
GNU Classpath (0.95) |