Math.java revision 5839b909d9528b7726e678a4b696ed37df15d897
1/* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18package java.lang; 19 20/** 21 * Class Math provides basic math constants and operations such as trigonometric 22 * functions, hyperbolic functions, exponential, logarithms, etc. 23 */ 24public final class Math { 25 26 /** 27 * The double value closest to e, the base of the natural logarithm. 28 */ 29 public static final double E = 2.718281828459045; 30 31 /** 32 * The double value closest to pi, the ratio of a circle's circumference to 33 * its diameter. 34 */ 35 public static final double PI = 3.141592653589793; 36 37 private static java.util.Random random; 38 39 /** 40 * Prevents this class from being instantiated. 41 */ 42 private Math() { 43 } 44 45 /** 46 * Returns the absolute value of the argument. 47 * <p> 48 * Special cases: 49 * <ul> 50 * <li>{@code abs(-0.0) = +0.0}</li> 51 * <li>{@code abs(+infinity) = +infinity}</li> 52 * <li>{@code abs(-infinity) = +infinity}</li> 53 * <li>{@code abs(NaN) = NaN}</li> 54 * </ul> 55 * 56 * @param d 57 * the value whose absolute value has to be computed. 58 * @return the absolute value of the argument. 59 */ 60 public static double abs(double d) { 61 long bits = Double.doubleToLongBits(d); 62 bits &= 0x7fffffffffffffffL; 63 return Double.longBitsToDouble(bits); 64 } 65 66 /** 67 * Returns the absolute value of the argument. 68 * <p> 69 * Special cases: 70 * <ul> 71 * <li>{@code abs(-0.0) = +0.0}</li> 72 * <li>{@code abs(+infinity) = +infinity}</li> 73 * <li>{@code abs(-infinity) = +infinity}</li> 74 * <li>{@code abs(NaN) = NaN}</li> 75 * </ul> 76 * 77 * @param f 78 * the value whose absolute value has to be computed. 79 * @return the argument if it is positive, otherwise the negation of the 80 * argument. 81 */ 82 public static float abs(float f) { 83 int bits = Float.floatToIntBits(f); 84 bits &= 0x7fffffff; 85 return Float.intBitsToFloat(bits); 86 } 87 88 /** 89 * Returns the absolute value of the argument. 90 * <p> 91 * If the argument is {@code Integer.MIN_VALUE}, {@code Integer.MIN_VALUE} 92 * is returned. 93 * 94 * @param i 95 * the value whose absolute value has to be computed. 96 * @return the argument if it is positive, otherwise the negation of the 97 * argument. 98 */ 99 public static int abs(int i) { 100 return i >= 0 ? i : -i; 101 } 102 103 /** 104 * Returns the absolute value of the argument. If the argument is {@code 105 * Long.MIN_VALUE}, {@code Long.MIN_VALUE} is returned. 106 * 107 * @param l 108 * the value whose absolute value has to be computed. 109 * @return the argument if it is positive, otherwise the negation of the 110 * argument. 111 */ 112 public static long abs(long l) { 113 return l >= 0 ? l : -l; 114 } 115 116 /** 117 * Returns the closest double approximation of the arc cosine of the 118 * argument within the range {@code [0..pi]}. The returned result is within 119 * 1 ulp (unit in the last place) of the real result. 120 * <p> 121 * Special cases: 122 * <ul> 123 * <li>{@code acos((anything > 1) = NaN}</li> 124 * <li>{@code acos((anything < -1) = NaN}</li> 125 * <li>{@code acos(NaN) = NaN}</li> 126 * </ul> 127 * 128 * @param d 129 * the value to compute arc cosine of. 130 * @return the arc cosine of the argument. 131 */ 132 public static native double acos(double d); 133 134 /** 135 * Returns the closest double approximation of the arc sine of the argument 136 * within the range {@code [-pi/2..pi/2]}. The returned result is within 1 137 * ulp (unit in the last place) of the real result. 138 * <p> 139 * Special cases: 140 * <ul> 141 * <li>{@code asin((anything > 1)) = NaN}</li> 142 * <li>{@code asin((anything < -1)) = NaN}</li> 143 * <li>{@code asin(NaN) = NaN}</li> 144 * </ul> 145 * 146 * @param d 147 * the value whose arc sine has to be computed. 148 * @return the arc sine of the argument. 149 */ 150 public static native double asin(double d); 151 152 /** 153 * Returns the closest double approximation of the arc tangent of the 154 * argument within the range {@code [-pi/2..pi/2]}. The returned result is 155 * within 1 ulp (unit in the last place) of the real result. 156 * <p> 157 * Special cases: 158 * <ul> 159 * <li>{@code atan(+0.0) = +0.0}</li> 160 * <li>{@code atan(-0.0) = -0.0}</li> 161 * <li>{@code atan(+infinity) = +pi/2}</li> 162 * <li>{@code atan(-infinity) = -pi/2}</li> 163 * <li>{@code atan(NaN) = NaN}</li> 164 * </ul> 165 * 166 * @param d 167 * the value whose arc tangent has to be computed. 168 * @return the arc tangent of the argument. 169 */ 170 public static native double atan(double d); 171 172 /** 173 * Returns the closest double approximation of the arc tangent of {@code 174 * y/x} within the range {@code [-pi..pi]}. This is the angle of the polar 175 * representation of the rectangular coordinates (x,y). The returned result 176 * is within 2 ulps (units in the last place) of the real result. 177 * <p> 178 * Special cases: 179 * <ul> 180 * <li>{@code atan2((anything), NaN ) = NaN;}</li> 181 * <li>{@code atan2(NaN , (anything) ) = NaN;}</li> 182 * <li>{@code atan2(+0.0, +(anything but NaN)) = +0.0}</li> 183 * <li>{@code atan2(-0.0, +(anything but NaN)) = -0.0}</li> 184 * <li>{@code atan2(+0.0, -(anything but NaN)) = +pi}</li> 185 * <li>{@code atan2(-0.0, -(anything but NaN)) = -pi}</li> 186 * <li>{@code atan2(+(anything but 0 and NaN), 0) = +pi/2}</li> 187 * <li>{@code atan2(-(anything but 0 and NaN), 0) = -pi/2}</li> 188 * <li>{@code atan2(+(anything but infinity and NaN), +infinity)} {@code =} 189 * {@code +0.0}</li> 190 * <li>{@code atan2(-(anything but infinity and NaN), +infinity)} {@code =} 191 * {@code -0.0}</li> 192 * <li>{@code atan2(+(anything but infinity and NaN), -infinity) = +pi}</li> 193 * <li>{@code atan2(-(anything but infinity and NaN), -infinity) = -pi}</li> 194 * <li>{@code atan2(+infinity, +infinity ) = +pi/4}</li> 195 * <li>{@code atan2(-infinity, +infinity ) = -pi/4}</li> 196 * <li>{@code atan2(+infinity, -infinity ) = +3pi/4}</li> 197 * <li>{@code atan2(-infinity, -infinity ) = -3pi/4}</li> 198 * <li>{@code atan2(+infinity, (anything but,0, NaN, and infinity))} {@code 199 * =} {@code +pi/2}</li> 200 * <li>{@code atan2(-infinity, (anything but,0, NaN, and infinity))} {@code 201 * =} {@code -pi/2}</li> 202 * </ul> 203 * 204 * @param y 205 * the numerator of the value whose atan has to be computed. 206 * @param x 207 * the denominator of the value whose atan has to be computed. 208 * @return the arc tangent of {@code y/x}. 209 */ 210 public static native double atan2(double x, double y); 211 212 /** 213 * Returns the closest double approximation of the cube root of the 214 * argument. 215 * <p> 216 * Special cases: 217 * <ul> 218 * <li>{@code cbrt(+0.0) = +0.0}</li> 219 * <li>{@code cbrt(-0.0) = -0.0}</li> 220 * <li>{@code cbrt(+infinity) = +infinity}</li> 221 * <li>{@code cbrt(-infinity) = -infinity}</li> 222 * <li>{@code cbrt(NaN) = NaN}</li> 223 * </ul> 224 * 225 * @param d 226 * the value whose cube root has to be computed. 227 * @return the cube root of the argument. 228 */ 229 public static native double cbrt(double d); 230 231 /** 232 * Returns the double conversion of the most negative (closest to negative 233 * infinity) integer value which is greater than the argument. 234 * <p> 235 * Special cases: 236 * <ul> 237 * <li>{@code ceil(+0.0) = +0.0}</li> 238 * <li>{@code ceil(-0.0) = -0.0}</li> 239 * <li>{@code ceil((anything in range (-1,0)) = -0.0}</li> 240 * <li>{@code ceil(+infinity) = +infinity}</li> 241 * <li>{@code ceil(-infinity) = -infinity}</li> 242 * <li>{@code ceil(NaN) = NaN}</li> 243 * </ul> 244 * 245 * @param d 246 * the value whose closest integer value has to be computed. 247 * @return the ceiling of the argument. 248 */ 249 public static native double ceil(double d); 250 251 /** 252 * Returns the closest double approximation of the cosine of the argument. 253 * The returned result is within 1 ulp (unit in the last place) of the real 254 * result. 255 * <p> 256 * Special cases: 257 * <ul> 258 * <li>{@code cos(+infinity) = NaN}</li> 259 * <li>{@code cos(-infinity) = NaN}</li> 260 * <li>{@code cos(NaN) = NaN}</li> 261 * </ul> 262 * 263 * @param d 264 * the angle whose cosine has to be computed, in radians. 265 * @return the cosine of the argument. 266 */ 267 public static native double cos(double d); 268 269 /** 270 * Returns the closest double approximation of the hyperbolic cosine of the 271 * argument. The returned result is within 2.5 ulps (units in the last 272 * place) of the real result. 273 * <p> 274 * Special cases: 275 * <ul> 276 * <li>{@code cosh(+infinity) = +infinity}</li> 277 * <li>{@code cosh(-infinity) = +infinity}</li> 278 * <li>{@code cosh(NaN) = NaN}</li> 279 * </ul> 280 * 281 * @param d 282 * the value whose hyperbolic cosine has to be computed. 283 * @return the hyperbolic cosine of the argument. 284 */ 285 public static native double cosh(double d); 286 287 /** 288 * Returns the closest double approximation of the raising "e" to the power 289 * of the argument. The returned result is within 1 ulp (unit in the last 290 * place) of the real result. 291 * <p> 292 * Special cases: 293 * <ul> 294 * <li>{@code exp(+infinity) = +infinity}</li> 295 * <li>{@code exp(-infinity) = +0.0}</li> 296 * <li>{@code exp(NaN) = NaN}</li> 297 * </ul> 298 * 299 * @param d 300 * the value whose exponential has to be computed. 301 * @return the exponential of the argument. 302 */ 303 public static native double exp(double d); 304 305 /** 306 * Returns the closest double approximation of <i>{@code e}</i><sup> {@code 307 * d}</sup>{@code - 1}. If the argument is very close to 0, it is much more 308 * accurate to use {@code expm1(d)+1} than {@code exp(d)} (due to 309 * cancellation of significant digits). The returned result is within 1 ulp 310 * (unit in the last place) of the real result. 311 * <p> 312 * For any finite input, the result is not less than -1.0. If the real 313 * result is within 0.5 ulp of -1, -1.0 is returned. 314 * <p> 315 * Special cases: 316 * <ul> 317 * <li>{@code expm1(+0.0) = +0.0}</li> 318 * <li>{@code expm1(-0.0) = -0.0}</li> 319 * <li>{@code expm1(+infinity) = +infinity}</li> 320 * <li>{@code expm1(-infinity) = -1.0}</li> 321 * <li>{@code expm1(NaN) = NaN}</li> 322 * </ul> 323 * 324 * @param d 325 * the value to compute the <i>{@code e}</i><sup>{@code d} </sup> 326 * {@code - 1} of. 327 * @return the <i>{@code e}</i><sup>{@code d}</sup>{@code - 1} value of the 328 * argument. 329 */ 330 public static native double expm1(double d); 331 332 /** 333 * Returns the double conversion of the most positive (closest to positive 334 * infinity) integer value which is less than the argument. 335 * <p> 336 * Special cases: 337 * <ul> 338 * <li>{@code floor(+0.0) = +0.0}</li> 339 * <li>{@code floor(-0.0) = -0.0}</li> 340 * <li>{@code floor(+infinity) = +infinity}</li> 341 * <li>{@code floor(-infinity) = -infinity}</li> 342 * <li>{@code floor(NaN) = NaN}</li> 343 * </ul> 344 * 345 * @param d 346 * the value whose closest integer value has to be computed. 347 * @return the floor of the argument. 348 */ 349 public static native double floor(double d); 350 351 /** 352 * Returns {@code sqrt(}<i>{@code x}</i><sup>{@code 2}</sup>{@code +} <i> 353 * {@code y}</i><sup>{@code 2}</sup>{@code )}. The final result is without 354 * medium underflow or overflow. The returned result is within 1 ulp (unit 355 * in the last place) of the real result. If one parameter remains constant, 356 * the result should be semi-monotonic. 357 * <p> 358 * Special cases: 359 * <ul> 360 * <li>{@code hypot(+infinity, (anything including NaN)) = +infinity}</li> 361 * <li>{@code hypot(-infinity, (anything including NaN)) = +infinity}</li> 362 * <li>{@code hypot((anything including NaN), +infinity) = +infinity}</li> 363 * <li>{@code hypot((anything including NaN), -infinity) = +infinity}</li> 364 * <li>{@code hypot(NaN, NaN) = NaN}</li> 365 * </ul> 366 * 367 * @param x 368 * a double number. 369 * @param y 370 * a double number. 371 * @return the {@code sqrt(}<i>{@code x}</i><sup>{@code 2}</sup>{@code +} 372 * <i> {@code y}</i><sup>{@code 2}</sup>{@code )} value of the 373 * arguments. 374 */ 375 public static native double hypot(double x, double y); 376 377 /** 378 * Returns the remainder of dividing {@code x} by {@code y} using the IEEE 379 * 754 rules. The result is {@code x-round(x/p)*p} where {@code round(x/p)} 380 * is the nearest integer (rounded to even), but without numerical 381 * cancellation problems. 382 * <p> 383 * Special cases: 384 * <ul> 385 * <li>{@code IEEEremainder((anything), 0) = NaN}</li> 386 * <li>{@code IEEEremainder(+infinity, (anything)) = NaN}</li> 387 * <li>{@code IEEEremainder(-infinity, (anything)) = NaN}</li> 388 * <li>{@code IEEEremainder(NaN, (anything)) = NaN}</li> 389 * <li>{@code IEEEremainder((anything), NaN) = NaN}</li> 390 * <li>{@code IEEEremainder(x, +infinity) = x } where x is anything but 391 * +/-infinity</li> 392 * <li>{@code IEEEremainder(x, -infinity) = x } where x is anything but 393 * +/-infinity</li> 394 * </ul> 395 * 396 * @param x 397 * the numerator of the operation. 398 * @param y 399 * the denominator of the operation. 400 * @return the IEEE754 floating point reminder of of {@code x/y}. 401 */ 402 public static native double IEEEremainder(double x, double y); 403 404 /** 405 * Returns the closest double approximation of the natural logarithm of the 406 * argument. The returned result is within 1 ulp (unit in the last place) of 407 * the real result. 408 * <p> 409 * Special cases: 410 * <ul> 411 * <li>{@code log(+0.0) = -infinity}</li> 412 * <li>{@code log(-0.0) = -infinity}</li> 413 * <li>{@code log((anything < 0) = NaN}</li> 414 * <li>{@code log(+infinity) = +infinity}</li> 415 * <li>{@code log(-infinity) = NaN}</li> 416 * <li>{@code log(NaN) = NaN}</li> 417 * </ul> 418 * 419 * @param d 420 * the value whose log has to be computed. 421 * @return the natural logarithm of the argument. 422 */ 423 public static native double log(double d); 424 425 /** 426 * Returns the closest double approximation of the base 10 logarithm of the 427 * argument. The returned result is within 1 ulp (unit in the last place) of 428 * the real result. 429 * <p> 430 * Special cases: 431 * <ul> 432 * <li>{@code log10(+0.0) = -infinity}</li> 433 * <li>{@code log10(-0.0) = -infinity}</li> 434 * <li>{@code log10((anything < 0) = NaN}</li> 435 * <li>{@code log10(+infinity) = +infinity}</li> 436 * <li>{@code log10(-infinity) = NaN}</li> 437 * <li>{@code log10(NaN) = NaN}</li> 438 * </ul> 439 * 440 * @param d 441 * the value whose base 10 log has to be computed. 442 * @return the natural logarithm of the argument. 443 */ 444 public static native double log10(double d); 445 446 /** 447 * Returns the closest double approximation of the natural logarithm of the 448 * sum of the argument and 1. If the argument is very close to 0, it is much 449 * more accurate to use {@code log1p(d)} than {@code log(1.0+d)} (due to 450 * numerical cancellation). The returned result is within 1 ulp (unit in the 451 * last place) of the real result and is semi-monotonic. 452 * <p> 453 * Special cases: 454 * <ul> 455 * <li>{@code log1p(+0.0) = +0.0}</li> 456 * <li>{@code log1p(-0.0) = -0.0}</li> 457 * <li>{@code log1p((anything < 1)) = NaN}</li> 458 * <li>{@code log1p(-1.0) = -infinity}</li> 459 * <li>{@code log1p(+infinity) = +infinity}</li> 460 * <li>{@code log1p(-infinity) = NaN}</li> 461 * <li>{@code log1p(NaN) = NaN}</li> 462 * </ul> 463 * 464 * @param d 465 * the value to compute the {@code ln(1+d)} of. 466 * @return the natural logarithm of the sum of the argument and 1. 467 */ 468 public static native double log1p(double d); 469 470 /** 471 * Returns the most positive (closest to positive infinity) of the two 472 * arguments. 473 * <p> 474 * Special cases: 475 * <ul> 476 * <li>{@code max(NaN, (anything)) = NaN}</li> 477 * <li>{@code max((anything), NaN) = NaN}</li> 478 * <li>{@code max(+0.0, -0.0) = +0.0}</li> 479 * <li>{@code max(-0.0, +0.0) = +0.0}</li> 480 * </ul> 481 * 482 * @param d1 483 * the first argument. 484 * @param d2 485 * the second argument. 486 * @return the larger of {@code d1} and {@code d2}. 487 */ 488 public static double max(double d1, double d2) { 489 if (d1 > d2) { 490 return d1; 491 } 492 if (d1 < d2) { 493 return d2; 494 } 495 /* if either arg is NaN, return NaN */ 496 if (d1 != d2) { 497 return Double.NaN; 498 } 499 /* max(+0.0,-0.0) == +0.0 */ 500 /* 0 == Double.doubleToRawLongBits(0.0d) */ 501 if (Double.doubleToRawLongBits(d1) != 0) { 502 return d2; 503 } 504 return 0.0d; 505 } 506 507 /** 508 * Returns the most positive (closest to positive infinity) of the two 509 * arguments. 510 * <p> 511 * Special cases: 512 * <ul> 513 * <li>{@code max(NaN, (anything)) = NaN}</li> 514 * <li>{@code max((anything), NaN) = NaN}</li> 515 * <li>{@code max(+0.0, -0.0) = +0.0}</li> 516 * <li>{@code max(-0.0, +0.0) = +0.0}</li> 517 * </ul> 518 * 519 * @param f1 520 * the first argument. 521 * @param f2 522 * the second argument. 523 * @return the larger of {@code f1} and {@code f2}. 524 */ 525 public static float max(float f1, float f2) { 526 if (f1 > f2) { 527 return f1; 528 } 529 if (f1 < f2) { 530 return f2; 531 } 532 /* if either arg is NaN, return NaN */ 533 if (f1 != f2) { 534 return Float.NaN; 535 } 536 /* max(+0.0,-0.0) == +0.0 */ 537 /* 0 == Float.floatToRawIntBits(0.0f) */ 538 if (Float.floatToRawIntBits(f1) != 0) { 539 return f2; 540 } 541 return 0.0f; 542 } 543 544 /** 545 * Returns the most positive (closest to positive infinity) of the two 546 * arguments. 547 * 548 * @param i1 549 * the first argument. 550 * @param i2 551 * the second argument. 552 * @return the larger of {@code i1} and {@code i2}. 553 */ 554 public static int max(int i1, int i2) { 555 return i1 > i2 ? i1 : i2; 556 } 557 558 /** 559 * Returns the most positive (closest to positive infinity) of the two 560 * arguments. 561 * 562 * @param l1 563 * the first argument. 564 * @param l2 565 * the second argument. 566 * @return the larger of {@code l1} and {@code l2}. 567 */ 568 public static long max(long l1, long l2) { 569 return l1 > l2 ? l1 : l2; 570 } 571 572 /** 573 * Returns the most negative (closest to negative infinity) of the two 574 * arguments. 575 * <p> 576 * Special cases: 577 * <ul> 578 * <li>{@code min(NaN, (anything)) = NaN}</li> 579 * <li>{@code min((anything), NaN) = NaN}</li> 580 * <li>{@code min(+0.0, -0.0) = -0.0}</li> 581 * <li>{@code min(-0.0, +0.0) = -0.0}</li> 582 * </ul> 583 * 584 * @param d1 585 * the first argument. 586 * @param d2 587 * the second argument. 588 * @return the smaller of {@code d1} and {@code d2}. 589 */ 590 public static double min(double d1, double d2) { 591 if (d1 > d2) { 592 return d2; 593 } 594 if (d1 < d2) { 595 return d1; 596 } 597 /* if either arg is NaN, return NaN */ 598 if (d1 != d2) { 599 return Double.NaN; 600 } 601 /* min(+0.0,-0.0) == -0.0 */ 602 /* 0x8000000000000000L == Double.doubleToRawLongBits(-0.0d) */ 603 if (Double.doubleToRawLongBits(d1) == 0x8000000000000000L) { 604 return -0.0d; 605 } 606 return d2; 607 } 608 609 /** 610 * Returns the most negative (closest to negative infinity) of the two 611 * arguments. 612 * <p> 613 * Special cases: 614 * <ul> 615 * <li>{@code min(NaN, (anything)) = NaN}</li> 616 * <li>{@code min((anything), NaN) = NaN}</li> 617 * <li>{@code min(+0.0, -0.0) = -0.0}</li> 618 * <li>{@code min(-0.0, +0.0) = -0.0}</li> 619 * </ul> 620 * 621 * @param f1 622 * the first argument. 623 * @param f2 624 * the second argument. 625 * @return the smaller of {@code f1} and {@code f2}. 626 */ 627 public static float min(float f1, float f2) { 628 if (f1 > f2) { 629 return f2; 630 } 631 if (f1 < f2) { 632 return f1; 633 } 634 /* if either arg is NaN, return NaN */ 635 if (f1 != f2) { 636 return Float.NaN; 637 } 638 /* min(+0.0,-0.0) == -0.0 */ 639 /* 0x80000000 == Float.floatToRawIntBits(-0.0f) */ 640 if (Float.floatToRawIntBits(f1) == 0x80000000) { 641 return -0.0f; 642 } 643 return f2; 644 } 645 646 /** 647 * Returns the most negative (closest to negative infinity) of the two 648 * arguments. 649 * 650 * @param i1 651 * the first argument. 652 * @param i2 653 * the second argument. 654 * @return the smaller of {@code i1} and {@code i2}. 655 */ 656 public static int min(int i1, int i2) { 657 return i1 < i2 ? i1 : i2; 658 } 659 660 /** 661 * Returns the most negative (closest to negative infinity) of the two 662 * arguments. 663 * 664 * @param l1 665 * the first argument. 666 * @param l2 667 * the second argument. 668 * @return the smaller of {@code l1} and {@code l2}. 669 */ 670 public static long min(long l1, long l2) { 671 return l1 < l2 ? l1 : l2; 672 } 673 674 /** 675 * Returns the closest double approximation of the result of raising {@code 676 * x} to the power of {@code y}. 677 * <p> 678 * Special cases: 679 * <ul> 680 * <li>{@code pow((anything), +0.0) = 1.0}</li> 681 * <li>{@code pow((anything), -0.0) = 1.0}</li> 682 * <li>{@code pow(x, 1.0) = x}</li> 683 * <li>{@code pow((anything), NaN) = NaN}</li> 684 * <li>{@code pow(NaN, (anything except 0)) = NaN}</li> 685 * <li>{@code pow(+/-(|x| > 1), +infinity) = +infinity}</li> 686 * <li>{@code pow(+/-(|x| > 1), -infinity) = +0.0}</li> 687 * <li>{@code pow(+/-(|x| < 1), +infinity) = +0.0}</li> 688 * <li>{@code pow(+/-(|x| < 1), -infinity) = +infinity}</li> 689 * <li>{@code pow(+/-1.0 , +infinity) = NaN}</li> 690 * <li>{@code pow(+/-1.0 , -infinity) = NaN}</li> 691 * <li>{@code pow(+0.0, (+anything except 0, NaN)) = +0.0}</li> 692 * <li>{@code pow(-0.0, (+anything except 0, NaN, odd integer)) = +0.0}</li> 693 * <li>{@code pow(+0.0, (-anything except 0, NaN)) = +infinity}</li> 694 * <li>{@code pow(-0.0, (-anything except 0, NAN, odd integer))} {@code =} 695 * {@code +infinity}</li> 696 * <li>{@code pow(-0.0, (odd integer)) = -pow( +0 , (odd integer) )}</li> 697 * <li>{@code pow(+infinity, (+anything except 0, NaN)) = +infinity}</li> 698 * <li>{@code pow(+infinity, (-anything except 0, NaN)) = +0.0}</li> 699 * <li>{@code pow(-infinity, (anything)) = -pow(0, (-anything))}</li> 700 * <li>{@code pow((-anything), (integer))} {@code =} {@code 701 * pow(-1,(integer))*pow(+anything,integer) }</li> 702 * <li>{@code pow((-anything except 0 and inf), (non-integer)) = NAN}</li> 703 * </ul> 704 * 705 * @param x 706 * the base of the operation. 707 * @param y 708 * the exponent of the operation. 709 * @return {@code x} to the power of {@code y}. 710 */ 711 public static native double pow(double x, double y); 712 713 /** 714 * Returns the double conversion of the result of rounding the argument to 715 * an integer. Tie breaks are rounded towards even. 716 * <p> 717 * Special cases: 718 * <ul> 719 * <li>{@code rint(+0.0) = +0.0}</li> 720 * <li>{@code rint(-0.0) = -0.0}</li> 721 * <li>{@code rint(+infinity) = +infinity}</li> 722 * <li>{@code rint(-infinity) = -infinity}</li> 723 * <li>{@code rint(NaN) = NaN}</li> 724 * </ul> 725 * 726 * @param d 727 * the value to be rounded. 728 * @return the closest integer to the argument (as a double). 729 */ 730 public static native double rint(double d); 731 732 /** 733 * Returns the result of rounding the argument to an integer. The result is 734 * equivalent to {@code (long) Math.floor(d+0.5)}. 735 * <p> 736 * Special cases: 737 * <ul> 738 * <li>{@code round(+0.0) = +0.0}</li> 739 * <li>{@code round(-0.0) = +0.0}</li> 740 * <li>{@code round((anything > Long.MAX_VALUE) = Long.MAX_VALUE}</li> 741 * <li>{@code round((anything < Long.MIN_VALUE) = Long.MIN_VALUE}</li> 742 * <li>{@code round(+infintiy) = Long.MAX_VALUE}</li> 743 * <li>{@code round(-infintiy) = Long.MIN_VALUE}</li> 744 * <li>{@code round(NaN) = +0.0}</li> 745 * </ul> 746 * 747 * @param d 748 * the value to be rounded. 749 * @return the closest integer to the argument. 750 */ 751 public static long round(double d) { 752 // check for NaN 753 if (d != d) { 754 return 0L; 755 } 756 return (long) floor(d + 0.5d); 757 } 758 759 /** 760 * Returns the result of rounding the argument to an integer. The result is 761 * equivalent to {@code (int) Math.floor(f+0.5)}. 762 * <p> 763 * Special cases: 764 * <ul> 765 * <li>{@code round(+0.0) = +0.0}</li> 766 * <li>{@code round(-0.0) = +0.0}</li> 767 * <li>{@code round((anything > Integer.MAX_VALUE) = Integer.MAX_VALUE}</li> 768 * <li>{@code round((anything < Integer.MIN_VALUE) = Integer.MIN_VALUE}</li> 769 * <li>{@code round(+infintiy) = Integer.MAX_VALUE}</li> 770 * <li>{@code round(-infintiy) = Integer.MIN_VALUE}</li> 771 * <li>{@code round(NaN) = +0.0}</li> 772 * </ul> 773 * 774 * @param f 775 * the value to be rounded. 776 * @return the closest integer to the argument. 777 */ 778 public static int round(float f) { 779 // check for NaN 780 if (f != f) { 781 return 0; 782 } 783 return (int) floor(f + 0.5f); 784 } 785 786 /** 787 * Returns the signum function of the argument. If the argument is less than 788 * zero, it returns -1.0. If the argument is greater than zero, 1.0 is 789 * returned. If the argument is either positive or negative zero, the 790 * argument is returned as result. 791 * <p> 792 * Special cases: 793 * <ul> 794 * <li>{@code signum(+0.0) = +0.0}</li> 795 * <li>{@code signum(-0.0) = -0.0}</li> 796 * <li>{@code signum(+infinity) = +1.0}</li> 797 * <li>{@code signum(-infinity) = -1.0}</li> 798 * <li>{@code signum(NaN) = NaN}</li> 799 * </ul> 800 * 801 * @param d 802 * the value whose signum has to be computed. 803 * @return the value of the signum function. 804 */ 805 public static double signum(double d) { 806 return StrictMath.signum(d); 807 } 808 809 /** 810 * Returns the signum function of the argument. If the argument is less than 811 * zero, it returns -1.0. If the argument is greater than zero, 1.0 is 812 * returned. If the argument is either positive or negative zero, the 813 * argument is returned as result. 814 * <p> 815 * Special cases: 816 * <ul> 817 * <li>{@code signum(+0.0) = +0.0}</li> 818 * <li>{@code signum(-0.0) = -0.0}</li> 819 * <li>{@code signum(+infinity) = +1.0}</li> 820 * <li>{@code signum(-infinity) = -1.0}</li> 821 * <li>{@code signum(NaN) = NaN}</li> 822 * </ul> 823 * 824 * @param f 825 * the value whose signum has to be computed. 826 * @return the value of the signum function. 827 */ 828 public static float signum(float f) { 829 return StrictMath.signum(f); 830 } 831 832 /** 833 * Returns the closest double approximation of the sine of the argument. The 834 * returned result is within 1 ulp (unit in the last place) of the real 835 * result. 836 * <p> 837 * Special cases: 838 * <ul> 839 * <li>{@code sin(+0.0) = +0.0}</li> 840 * <li>{@code sin(-0.0) = -0.0}</li> 841 * <li>{@code sin(+infinity) = NaN}</li> 842 * <li>{@code sin(-infinity) = NaN}</li> 843 * <li>{@code sin(NaN) = NaN}</li> 844 * </ul> 845 * 846 * @param d 847 * the angle whose sin has to be computed, in radians. 848 * @return the sine of the argument. 849 */ 850 public static native double sin(double d); 851 852 /** 853 * Returns the closest double approximation of the hyperbolic sine of the 854 * argument. The returned result is within 2.5 ulps (units in the last 855 * place) of the real result. 856 * <p> 857 * Special cases: 858 * <ul> 859 * <li>{@code sinh(+0.0) = +0.0}</li> 860 * <li>{@code sinh(-0.0) = -0.0}</li> 861 * <li>{@code sinh(+infinity) = +infinity}</li> 862 * <li>{@code sinh(-infinity) = -infinity}</li> 863 * <li>{@code sinh(NaN) = NaN}</li> 864 * </ul> 865 * 866 * @param d 867 * the value whose hyperbolic sine has to be computed. 868 * @return the hyperbolic sine of the argument. 869 */ 870 public static native double sinh(double d); 871 872 /** 873 * Returns the closest double approximation of the square root of the 874 * argument. 875 * <p> 876 * Special cases: 877 * <ul> 878 * <li>{@code sqrt(+0.0) = +0.0}</li> 879 * <li>{@code sqrt(-0.0) = -0.0}</li> 880 * <li>{@code sqrt( (anything < 0) ) = NaN}</li> 881 * <li>{@code sqrt(+infinity) = +infinity}</li> 882 * <li>{@code sqrt(NaN) = NaN}</li> 883 * </ul> 884 * 885 * @param d 886 * the value whose square root has to be computed. 887 * @return the square root of the argument. 888 */ 889 public static native double sqrt(double d); 890 891 /** 892 * Returns the closest double approximation of the tangent of the argument. 893 * The returned result is within 1 ulp (unit in the last place) of the real 894 * result. 895 * <p> 896 * Special cases: 897 * <ul> 898 * <li>{@code tan(+0.0) = +0.0}</li> 899 * <li>{@code tan(-0.0) = -0.0}</li> 900 * <li>{@code tan(+infinity) = NaN}</li> 901 * <li>{@code tan(-infinity) = NaN}</li> 902 * <li>{@code tan(NaN) = NaN}</li> 903 * </ul> 904 * 905 * @param d 906 * the angle whose tangens has to be computed, in radians. 907 * @return the tangent of the argument. 908 */ 909 public static native double tan(double d); 910 911 /** 912 * Returns the closest double approximation of the hyperbolic tangent of the 913 * argument. The absolute value is always less than 1. The returned result 914 * is within 2.5 ulps (units in the last place) of the real result. If the 915 * real result is within 0.5ulp of 1 or -1, it should return exactly +1 or 916 * -1. 917 * <p> 918 * Special cases: 919 * <ul> 920 * <li>{@code tanh(+0.0) = +0.0}</li> 921 * <li>{@code tanh(-0.0) = -0.0}</li> 922 * <li>{@code tanh(+infinity) = +1.0}</li> 923 * <li>{@code tanh(-infinity) = -1.0}</li> 924 * <li>{@code tanh(NaN) = NaN}</li> 925 * </ul> 926 * 927 * @param d 928 * the value whose hyperbolic tangent has to be computed. 929 * @return the hyperbolic tangent of the argument. 930 */ 931 public static native double tanh(double d); 932 933 /** 934 * Returns a pseudo-random number between 0.0 (inclusive) and 1.0 935 * (exclusive). 936 * 937 * @return a pseudo-random number. 938 */ 939 public static double random() { 940 if (random == null) { 941 random = new java.util.Random(); 942 } 943 return random.nextDouble(); 944 } 945 946 /** 947 * Returns the measure in radians of the supplied degree angle. The result 948 * is {@code angdeg / 180 * pi}. 949 * <p> 950 * Special cases: 951 * <ul> 952 * <li>{@code toRadians(+0.0) = +0.0}</li> 953 * <li>{@code toRadians(-0.0) = -0.0}</li> 954 * <li>{@code toRadians(+infinity) = +infinity}</li> 955 * <li>{@code toRadians(-infinity) = -infinity}</li> 956 * <li>{@code toRadians(NaN) = NaN}</li> 957 * </ul> 958 * 959 * @param angdeg 960 * an angle in degrees. 961 * @return the radian measure of the angle. 962 */ 963 public static double toRadians(double angdeg) { 964 return angdeg / 180d * PI; 965 } 966 967 /** 968 * Returns the measure in degrees of the supplied radian angle. The result 969 * is {@code angrad * 180 / pi}. 970 * <p> 971 * Special cases: 972 * <ul> 973 * <li>{@code toDegrees(+0.0) = +0.0}</li> 974 * <li>{@code toDegrees(-0.0) = -0.0}</li> 975 * <li>{@code toDegrees(+infinity) = +infinity}</li> 976 * <li>{@code toDegrees(-infinity) = -infinity}</li> 977 * <li>{@code toDegrees(NaN) = NaN}</li> 978 * </ul> 979 * 980 * @param angrad 981 * an angle in radians. 982 * @return the degree measure of the angle. 983 */ 984 public static double toDegrees(double angrad) { 985 return angrad * 180d / PI; 986 } 987 988 /** 989 * Returns the argument's ulp (unit in the last place). The size of a ulp of 990 * a double value is the positive distance between this value and the double 991 * value next larger in magnitude. For non-NaN {@code x}, {@code ulp(-x) == 992 * ulp(x)}. 993 * <p> 994 * Special cases: 995 * <ul> 996 * <li>{@code ulp(+0.0) = Double.MIN_VALUE}</li> 997 * <li>{@code ulp(-0.0) = Double.MIN_VALUE}</li> 998 * <li>{@code ulp(+infintiy) = infinity}</li> 999 * <li>{@code ulp(-infintiy) = infinity}</li> 1000 * <li>{@code ulp(NaN) = NaN}</li> 1001 * </ul> 1002 * 1003 * @param d 1004 * the floating-point value to compute ulp of. 1005 * @return the size of a ulp of the argument. 1006 */ 1007 public static double ulp(double d) { 1008 // special cases 1009 if (Double.isInfinite(d)) { 1010 return Double.POSITIVE_INFINITY; 1011 } else if (d == Double.MAX_VALUE || d == -Double.MAX_VALUE) { 1012 return pow(2, 971); 1013 } 1014 d = abs(d); 1015 return nextafter(d, Double.MAX_VALUE) - d; 1016 } 1017 1018 /** 1019 * Returns the argument's ulp (unit in the last place). The size of a ulp of 1020 * a float value is the positive distance between this value and the float 1021 * value next larger in magnitude. For non-NaN {@code x}, {@code ulp(-x) == 1022 * ulp(x)}. 1023 * <p> 1024 * Special cases: 1025 * <ul> 1026 * <li>{@code ulp(+0.0) = Float.MIN_VALUE}</li> 1027 * <li>{@code ulp(-0.0) = Float.MIN_VALUE}</li> 1028 * <li>{@code ulp(+infintiy) = infinity}</li> 1029 * <li>{@code ulp(-infintiy) = infinity}</li> 1030 * <li>{@code ulp(NaN) = NaN}</li> 1031 * </ul> 1032 * 1033 * @param f 1034 * the floating-point value to compute ulp of. 1035 * @return the size of a ulp of the argument. 1036 */ 1037 public static float ulp(float f) { 1038 // special cases 1039 if (Float.isNaN(f)) { 1040 return Float.NaN; 1041 } else if (Float.isInfinite(f)) { 1042 return Float.POSITIVE_INFINITY; 1043 } else if (f == Float.MAX_VALUE || f == -Float.MAX_VALUE) { 1044 return (float) pow(2, 104); 1045 } 1046 f = abs(f); 1047 return nextafterf(f, Float.MAX_VALUE) - f; 1048 } 1049 1050 private native static double nextafter(double x, double y); 1051 1052 private native static float nextafterf(float x, float y); 1053} 1054