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