GNU Classpath (0.20) | |
Frames | No Frames |
1: /* java.lang.Math -- common mathematical functions, native allowed 2: Copyright (C) 1998, 2001, 2002, 2003 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: }
GNU Classpath (0.20) |