Source for java.lang.Math

   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:    *       &lt;&lt; 1) &gt;&gt;&gt; 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 &gt;= <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 &lt;= <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: }