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 18 package java.lang; 19 20 /** 21 * Class StrictMath provides basic math constants and operations such as 22 * trigonometric functions, hyperbolic functions, exponential, logarithms, etc. 23 * <p> 24 * In contrast to class {@link Math}, the methods in this class return exactly 25 * the same results on all platforms. Algorithms based on these methods thus 26 * behave the same (e.g. regarding numerical convergence) on all platforms, 27 * complying with the slogan "write once, run everywhere". On the other side, 28 * the implementation of class StrictMath may be less efficient than that of 29 * class Math, as class StrictMath cannot utilize platform specific features 30 * such as an extended precision math co-processors. 31 * <p> 32 * The methods in this class are specified using the "Freely Distributable Math 33 * Library" (fdlibm), version 5.3. 34 * <p> 35 * <a href="http://www.netlib.org/fdlibm/">http://www.netlib.org/fdlibm/</a> 36 */ 37 public final class StrictMath { 38 /** 39 * The double value closest to e, the base of the natural logarithm. 40 */ 41 public final static double E = Math.E; 42 43 /** 44 * The double value closest to pi, the ratio of a circle's circumference to 45 * its diameter. 46 */ 47 public final static double PI = Math.PI; 48 49 private static java.util.Random random; 50 51 /** 52 * Prevents this class from being instantiated. 53 */ StrictMath()54 private StrictMath() { 55 } 56 57 /** 58 * Returns the absolute value of the argument. 59 * <p> 60 * Special cases: 61 * <ul> 62 * <li>{@code abs(-0.0) = +0.0}</li> 63 * <li>{@code abs(+infinity) = +infinity}</li> 64 * <li>{@code abs(-infinity) = +infinity}</li> 65 * <li>{@code abs(NaN) = NaN}</li> 66 * </ul> 67 * 68 * @param d 69 * the value whose absolute value has to be computed. 70 * @return the absolute value of the argument. 71 */ abs(double d)72 public static double abs(double d) { 73 return Math.abs(d); 74 } 75 76 /** 77 * Returns the absolute value of the argument. 78 * <p> 79 * Special cases: 80 * <ul> 81 * <li>{@code abs(-0.0) = +0.0}</li> 82 * <li>{@code abs(+infinity) = +infinity}</li> 83 * <li>{@code abs(-infinity) = +infinity}</li> 84 * <li>{@code abs(NaN) = NaN}</li> 85 * </ul> 86 * 87 * @param f 88 * the value whose absolute value has to be computed. 89 * @return the argument if it is positive, otherwise the negation of the 90 * argument. 91 */ abs(float f)92 public static float abs(float f) { 93 return Math.abs(f); 94 } 95 96 /** 97 * Returns the absolute value of the argument. 98 * <p> 99 * If the argument is {@code Integer.MIN_VALUE}, {@code Integer.MIN_VALUE} 100 * is returned. 101 * 102 * @param i 103 * the value whose absolute value has to be computed. 104 * @return the argument if it is positive, otherwise the negation of the 105 * argument. 106 */ abs(int i)107 public static int abs(int i) { 108 return Math.abs(i); 109 } 110 111 /** 112 * Returns the absolute value of the argument. 113 * <p> 114 * If the argument is {@code Long.MIN_VALUE}, {@code Long.MIN_VALUE} is 115 * returned. 116 * 117 * @param l 118 * the value whose absolute value has to be computed. 119 * @return the argument if it is positive, otherwise the negation of the 120 * argument. 121 */ abs(long l)122 public static long abs(long l) { 123 return Math.abs(l); 124 } 125 126 /** 127 * Returns the closest double approximation of the arc cosine of the 128 * argument within the range {@code [0..pi]}. 129 * <p> 130 * Special cases: 131 * <ul> 132 * <li>{@code acos((anything > 1) = NaN}</li> 133 * <li>{@code acos((anything < -1) = NaN}</li> 134 * <li>{@code acos(NaN) = NaN}</li> 135 * </ul> 136 * 137 * @param d 138 * the value to compute arc cosine of. 139 * @return the arc cosine of the argument. 140 */ acos(double d)141 public static native double acos(double d); 142 143 /** 144 * Returns the closest double approximation of the arc sine of the argument 145 * within the range {@code [-pi/2..pi/2]}. 146 * <p> 147 * Special cases: 148 * <ul> 149 * <li>{@code asin((anything > 1)) = NaN}</li> 150 * <li>{@code asin((anything < -1)) = NaN}</li> 151 * <li>{@code asin(NaN) = NaN}</li> 152 * </ul> 153 * 154 * @param d 155 * the value whose arc sine has to be computed. 156 * @return the arc sine of the argument. 157 */ asin(double d)158 public static native double asin(double d); 159 160 /** 161 * Returns the closest double approximation of the arc tangent of the 162 * argument within the range {@code [-pi/2..pi/2]}. 163 * <p> 164 * Special cases: 165 * <ul> 166 * <li>{@code atan(+0.0) = +0.0}</li> 167 * <li>{@code atan(-0.0) = -0.0}</li> 168 * <li>{@code atan(+infinity) = +pi/2}</li> 169 * <li>{@code atan(-infinity) = -pi/2}</li> 170 * <li>{@code atan(NaN) = NaN}</li> 171 * </ul> 172 * 173 * @param d 174 * the value whose arc tangent has to be computed. 175 * @return the arc tangent of the argument. 176 */ atan(double d)177 public static native double atan(double d); 178 179 /** 180 * Returns the closest double approximation of the arc tangent of 181 * {@code y/x} within the range {@code [-pi..pi]}. This is the angle of the 182 * polar representation of the rectangular coordinates (x,y). 183 * <p> 184 * Special cases: 185 * <ul> 186 * <li>{@code atan2((anything), NaN ) = NaN;}</li> 187 * <li>{@code atan2(NaN , (anything) ) = NaN;}</li> 188 * <li>{@code atan2(+0.0, +(anything but NaN)) = +0.0}</li> 189 * <li>{@code atan2(-0.0, +(anything but NaN)) = -0.0}</li> 190 * <li>{@code atan2(+0.0, -(anything but NaN)) = +pi}</li> 191 * <li>{@code atan2(-0.0, -(anything but NaN)) = -pi}</li> 192 * <li>{@code atan2(+(anything but 0 and NaN), 0) = +pi/2}</li> 193 * <li>{@code atan2(-(anything but 0 and NaN), 0) = -pi/2}</li> 194 * <li>{@code atan2(+(anything but infinity and NaN), +infinity)} {@code =} 195 * {@code +0.0}</li> 196 * <li>{@code atan2(-(anything but infinity and NaN), +infinity)} {@code =} 197 * {@code -0.0}</li> 198 * <li>{@code atan2(+(anything but infinity and NaN), -infinity) = +pi}</li> 199 * <li>{@code atan2(-(anything but infinity and NaN), -infinity) = -pi}</li> 200 * <li>{@code atan2(+infinity, +infinity ) = +pi/4}</li> 201 * <li>{@code atan2(-infinity, +infinity ) = -pi/4}</li> 202 * <li>{@code atan2(+infinity, -infinity ) = +3pi/4}</li> 203 * <li>{@code atan2(-infinity, -infinity ) = -3pi/4}</li> 204 * <li>{@code atan2(+infinity, (anything but,0, NaN, and infinity))} 205 * {@code =} {@code +pi/2}</li> 206 * <li>{@code atan2(-infinity, (anything but,0, NaN, and infinity))} 207 * {@code =} {@code -pi/2}</li> 208 * </ul> 209 * 210 * @param y 211 * the numerator of the value whose atan has to be computed. 212 * @param x 213 * the denominator of the value whose atan has to be computed. 214 * @return the arc tangent of {@code y/x}. 215 */ atan2(double y, double x)216 public static native double atan2(double y, double x); 217 218 /** 219 * Returns the closest double approximation of the cube root of the 220 * argument. 221 * <p> 222 * Special cases: 223 * <ul> 224 * <li>{@code cbrt(+0.0) = +0.0}</li> 225 * <li>{@code cbrt(-0.0) = -0.0}</li> 226 * <li>{@code cbrt(+infinity) = +infinity}</li> 227 * <li>{@code cbrt(-infinity) = -infinity}</li> 228 * <li>{@code cbrt(NaN) = NaN}</li> 229 * </ul> 230 * 231 * @param d 232 * the value whose cube root has to be computed. 233 * @return the cube root of the argument. 234 */ cbrt(double d)235 public static native double cbrt(double d); 236 237 /** 238 * Returns the double conversion of the most negative (closest to negative 239 * infinity) integer value which is greater than the argument. 240 * <p> 241 * Special cases: 242 * <ul> 243 * <li>{@code ceil(+0.0) = +0.0}</li> 244 * <li>{@code ceil(-0.0) = -0.0}</li> 245 * <li>{@code ceil((anything in range (-1,0)) = -0.0}</li> 246 * <li>{@code ceil(+infinity) = +infinity}</li> 247 * <li>{@code ceil(-infinity) = -infinity}</li> 248 * <li>{@code ceil(NaN) = NaN}</li> 249 * </ul> 250 * 251 * @param d 252 * the value whose closest integer value has to be computed. 253 * @return the ceiling of the argument. 254 */ ceil(double d)255 public static native double ceil(double d); 256 257 258 /** 259 * Returns the closest double approximation of the hyperbolic cosine of the 260 * argument. 261 * <p> 262 * Special cases: 263 * <ul> 264 * <li>{@code cosh(+infinity) = +infinity}</li> 265 * <li>{@code cosh(-infinity) = +infinity}</li> 266 * <li>{@code cosh(NaN) = NaN}</li> 267 * </ul> 268 * 269 * @param d 270 * the value whose hyperbolic cosine has to be computed. 271 * @return the hyperbolic cosine of the argument. 272 */ cosh(double d)273 public static native double cosh(double d); 274 275 /** 276 * Returns the closest double approximation of the cosine of the argument. 277 * <p> 278 * Special cases: 279 * <ul> 280 * <li>{@code cos(+infinity) = NaN}</li> 281 * <li>{@code cos(-infinity) = NaN}</li> 282 * <li>{@code cos(NaN) = NaN}</li> 283 * </ul> 284 * 285 * @param d 286 * the angle whose cosine has to be computed, in radians. 287 * @return the cosine of the argument. 288 */ cos(double d)289 public static native double cos(double d); 290 291 /** 292 * Returns the closest double approximation of the raising "e" to the power 293 * of the argument. 294 * <p> 295 * Special cases: 296 * <ul> 297 * <li>{@code exp(+infinity) = +infinity}</li> 298 * <li>{@code exp(-infinity) = +0.0}</li> 299 * <li>{@code exp(NaN) = NaN}</li> 300 * </ul> 301 * 302 * @param d 303 * the value whose exponential has to be computed. 304 * @return the exponential of the argument. 305 */ exp(double d)306 public static native double exp(double d); 307 308 /** 309 * Returns the closest double approximation of <i>{@code e}</i><sup> 310 * {@code d}</sup>{@code - 1}. If the argument is very close to 0, it is 311 * much more accurate to use {@code expm1(d)+1} than {@code exp(d)} (due to 312 * cancellation of significant digits). 313 * <p> 314 * Special cases: 315 * <ul> 316 * <li>{@code expm1(+0.0) = +0.0}</li> 317 * <li>{@code expm1(-0.0) = -0.0}</li> 318 * <li>{@code expm1(+infinity) = +infinity}</li> 319 * <li>{@code expm1(-infinity) = -1.0}</li> 320 * <li>{@code expm1(NaN) = NaN}</li> 321 * </ul> 322 * 323 * @param d 324 * the value to compute the <i>{@code e}</i><sup>{@code d}</sup> 325 * {@code - 1} of. 326 * @return the <i>{@code e}</i><sup>{@code d}</sup>{@code - 1} value 327 * of the argument. 328 */ expm1(double d)329 public static native double expm1(double d); 330 331 /** 332 * Returns the double conversion of the most positive (closest to 333 * positive infinity) integer value which is less than the argument. 334 * <p> 335 * Special cases: 336 * <ul> 337 * <li>{@code floor(+0.0) = +0.0}</li> 338 * <li>{@code floor(-0.0) = -0.0}</li> 339 * <li>{@code floor(+infinity) = +infinity}</li> 340 * <li>{@code floor(-infinity) = -infinity}</li> 341 * <li>{@code floor(NaN) = NaN}</li> 342 * </ul> 343 * 344 * @param d the value whose closest integer value has to be computed. 345 * @return the floor of the argument. 346 */ floor(double d)347 public static native double floor(double d); 348 349 /** 350 * Returns {@code sqrt(}<i>{@code x}</i><sup>{@code 2}</sup>{@code +} 351 * <i> {@code y}</i><sup>{@code 2}</sup>{@code )}. The final result is 352 * without medium underflow or overflow. 353 * <p> 354 * Special cases: 355 * <ul> 356 * <li>{@code hypot(+infinity, (anything including NaN)) = +infinity}</li> 357 * <li>{@code hypot(-infinity, (anything including NaN)) = +infinity}</li> 358 * <li>{@code hypot((anything including NaN), +infinity) = +infinity}</li> 359 * <li>{@code hypot((anything including NaN), -infinity) = +infinity}</li> 360 * <li>{@code hypot(NaN, NaN) = NaN}</li> 361 * </ul> 362 * 363 * @param x 364 * a double number. 365 * @param y 366 * a double number. 367 * @return the {@code sqrt(}<i>{@code x}</i><sup>{@code 2}</sup>{@code +} 368 * <i> {@code y}</i><sup>{@code 2}</sup>{@code )} value of the 369 * arguments. 370 */ hypot(double x, double y)371 public static native double hypot(double x, double y); 372 373 /** 374 * Returns the remainder of dividing {@code x} by {@code y} using the IEEE 375 * 754 rules. The result is {@code x-round(x/p)*p} where {@code round(x/p)} 376 * is the nearest integer (rounded to even), but without numerical 377 * cancellation problems. 378 * <p> 379 * Special cases: 380 * <ul> 381 * <li>{@code IEEEremainder((anything), 0) = NaN}</li> 382 * <li>{@code IEEEremainder(+infinity, (anything)) = NaN}</li> 383 * <li>{@code IEEEremainder(-infinity, (anything)) = NaN}</li> 384 * <li>{@code IEEEremainder(NaN, (anything)) = NaN}</li> 385 * <li>{@code IEEEremainder((anything), NaN) = NaN}</li> 386 * <li>{@code IEEEremainder(x, +infinity) = x } where x is anything but 387 * +/-infinity</li> 388 * <li>{@code IEEEremainder(x, -infinity) = x } where x is anything but 389 * +/-infinity</li> 390 * </ul> 391 * 392 * @param x 393 * the numerator of the operation. 394 * @param y 395 * the denominator of the operation. 396 * @return the IEEE754 floating point reminder of of {@code x/y}. 397 */ IEEEremainder(double x, double y)398 public static native double IEEEremainder(double x, double y); 399 400 /** 401 * Returns the closest double approximation of the natural logarithm of the 402 * argument. 403 * <p> 404 * Special cases: 405 * <ul> 406 * <li>{@code log(+0.0) = -infinity}</li> 407 * <li>{@code log(-0.0) = -infinity}</li> 408 * <li>{@code log((anything < 0) = NaN}</li> 409 * <li>{@code log(+infinity) = +infinity}</li> 410 * <li>{@code log(-infinity) = NaN}</li> 411 * <li>{@code log(NaN) = NaN}</li> 412 * </ul> 413 * 414 * @param d 415 * the value whose log has to be computed. 416 * @return the natural logarithm of the argument. 417 */ log(double d)418 public static native double log(double d); 419 420 /** 421 * Returns the closest double approximation of the base 10 logarithm of the 422 * argument. 423 * <p> 424 * Special cases: 425 * <ul> 426 * <li>{@code log10(+0.0) = -infinity}</li> 427 * <li>{@code log10(-0.0) = -infinity}</li> 428 * <li>{@code log10((anything < 0) = NaN}</li> 429 * <li>{@code log10(+infinity) = +infinity}</li> 430 * <li>{@code log10(-infinity) = NaN}</li> 431 * <li>{@code log10(NaN) = NaN}</li> 432 * </ul> 433 * 434 * @param d 435 * the value whose base 10 log has to be computed. 436 * @return the natural logarithm of the argument. 437 */ log10(double d)438 public static native double log10(double d); 439 440 /** 441 * Returns the closest double approximation of the natural logarithm of the 442 * sum of the argument and 1. If the argument is very close to 0, it is much 443 * more accurate to use {@code log1p(d)} than {@code log(1.0+d)} (due to 444 * numerical cancellation). 445 * <p> 446 * Special cases: 447 * <ul> 448 * <li>{@code log1p(+0.0) = +0.0}</li> 449 * <li>{@code log1p(-0.0) = -0.0}</li> 450 * <li>{@code log1p((anything < 1)) = NaN}</li> 451 * <li>{@code log1p(-1.0) = -infinity}</li> 452 * <li>{@code log1p(+infinity) = +infinity}</li> 453 * <li>{@code log1p(-infinity) = NaN}</li> 454 * <li>{@code log1p(NaN) = NaN}</li> 455 * </ul> 456 * 457 * @param d 458 * the value to compute the {@code ln(1+d)} of. 459 * @return the natural logarithm of the sum of the argument and 1. 460 */ log1p(double d)461 public static native double log1p(double d); 462 463 /** 464 * Returns the most positive (closest to positive infinity) of the two 465 * arguments. 466 * <p> 467 * Special cases: 468 * <ul> 469 * <li>{@code max(NaN, (anything)) = NaN}</li> 470 * <li>{@code max((anything), NaN) = NaN}</li> 471 * <li>{@code max(+0.0, -0.0) = +0.0}</li> 472 * <li>{@code max(-0.0, +0.0) = +0.0}</li> 473 * </ul> 474 * 475 * @param d1 476 * the first argument. 477 * @param d2 478 * the second argument. 479 * @return the larger of {@code d1} and {@code d2}. 480 */ max(double d1, double d2)481 public static double max(double d1, double d2) { 482 if (d1 > d2) 483 return d1; 484 if (d1 < d2) 485 return d2; 486 /* if either arg is NaN, return NaN */ 487 if (d1 != d2) 488 return Double.NaN; 489 /* max( +0.0,-0.0) == +0.0 */ 490 if (d1 == 0.0 491 && ((Double.doubleToLongBits(d1) & Double.doubleToLongBits(d2)) & 0x8000000000000000L) == 0) 492 return 0.0; 493 return d1; 494 } 495 496 /** 497 * Returns the most positive (closest to positive infinity) of the two 498 * arguments. 499 * <p> 500 * Special cases: 501 * <ul> 502 * <li>{@code max(NaN, (anything)) = NaN}</li> 503 * <li>{@code max((anything), NaN) = NaN}</li> 504 * <li>{@code max(+0.0, -0.0) = +0.0}</li> 505 * <li>{@code max(-0.0, +0.0) = +0.0}</li> 506 * </ul> 507 * 508 * @param f1 509 * the first argument. 510 * @param f2 511 * the second argument. 512 * @return the larger of {@code f1} and {@code f2}. 513 */ max(float f1, float f2)514 public static float max(float f1, float f2) { 515 if (f1 > f2) 516 return f1; 517 if (f1 < f2) 518 return f2; 519 /* if either arg is NaN, return NaN */ 520 if (f1 != f2) 521 return Float.NaN; 522 /* max( +0.0,-0.0) == +0.0 */ 523 if (f1 == 0.0f 524 && ((Float.floatToIntBits(f1) & Float.floatToIntBits(f2)) & 0x80000000) == 0) 525 return 0.0f; 526 return f1; 527 } 528 529 /** 530 * Returns the most positive (closest to positive infinity) of the two 531 * arguments. 532 * 533 * @param i1 534 * the first argument. 535 * @param i2 536 * the second argument. 537 * @return the larger of {@code i1} and {@code i2}. 538 */ max(int i1, int i2)539 public static int max(int i1, int i2) { 540 return Math.max(i1, i2); 541 } 542 543 /** 544 * Returns the most positive (closest to positive infinity) of the two 545 * arguments. 546 * 547 * @param l1 548 * the first argument. 549 * @param l2 550 * the second argument. 551 * @return the larger of {@code l1} and {@code l2}. 552 */ max(long l1, long l2)553 public static long max(long l1, long l2) { 554 return Math.max(l1, l2); 555 } 556 557 /** 558 * Returns the most negative (closest to negative infinity) of the two 559 * arguments. 560 * <p> 561 * Special cases: 562 * <ul> 563 * <li>{@code min(NaN, (anything)) = NaN}</li> 564 * <li>{@code min((anything), NaN) = NaN}</li> 565 * <li>{@code min(+0.0, -0.0) = -0.0}</li> 566 * <li>{@code min(-0.0, +0.0) = -0.0}</li> 567 * </ul> 568 * 569 * @param d1 570 * the first argument. 571 * @param d2 572 * the second argument. 573 * @return the smaller of {@code d1} and {@code d2}. 574 */ min(double d1, double d2)575 public static double min(double d1, double d2) { 576 if (d1 > d2) 577 return d2; 578 if (d1 < d2) 579 return d1; 580 /* if either arg is NaN, return NaN */ 581 if (d1 != d2) 582 return Double.NaN; 583 /* min( +0.0,-0.0) == -0.0 */ 584 if (d1 == 0.0 585 && ((Double.doubleToLongBits(d1) | Double.doubleToLongBits(d2)) & 0x8000000000000000l) != 0) 586 return 0.0 * (-1.0); 587 return d1; 588 } 589 590 /** 591 * Returns the most negative (closest to negative infinity) of the two 592 * arguments. 593 * <p> 594 * Special cases: 595 * <ul> 596 * <li>{@code min(NaN, (anything)) = NaN}</li> 597 * <li>{@code min((anything), NaN) = NaN}</li> 598 * <li>{@code min(+0.0, -0.0) = -0.0}</li> 599 * <li>{@code min(-0.0, +0.0) = -0.0}</li> 600 * </ul> 601 * 602 * @param f1 603 * the first argument. 604 * @param f2 605 * the second argument. 606 * @return the smaller of {@code f1} and {@code f2}. 607 */ min(float f1, float f2)608 public static float min(float f1, float f2) { 609 if (f1 > f2) 610 return f2; 611 if (f1 < f2) 612 return f1; 613 /* if either arg is NaN, return NaN */ 614 if (f1 != f2) 615 return Float.NaN; 616 /* min( +0.0,-0.0) == -0.0 */ 617 if (f1 == 0.0f 618 && ((Float.floatToIntBits(f1) | Float.floatToIntBits(f2)) & 0x80000000) != 0) 619 return 0.0f * (-1.0f); 620 return f1; 621 } 622 623 /** 624 * Returns the most negative (closest to negative infinity) of the two 625 * arguments. 626 * 627 * @param i1 628 * the first argument. 629 * @param i2 630 * the second argument. 631 * @return the smaller of {@code i1} and {@code i2}. 632 */ min(int i1, int i2)633 public static int min(int i1, int i2) { 634 return Math.min(i1, i2); 635 } 636 637 /** 638 * Returns the most negative (closest to negative infinity) of the two 639 * arguments. 640 * 641 * @param l1 642 * the first argument. 643 * @param l2 644 * the second argument. 645 * @return the smaller of {@code l1} and {@code l2}. 646 */ min(long l1, long l2)647 public static long min(long l1, long l2) { 648 return Math.min(l1, l2); 649 } 650 651 /** 652 * Returns the closest double approximation of the result of raising 653 * {@code x} to the power of {@code y}. 654 * <p> 655 * Special cases: 656 * <ul> 657 * <li>{@code pow((anything), +0.0) = 1.0}</li> 658 * <li>{@code pow((anything), -0.0) = 1.0}</li> 659 * <li>{@code pow(x, 1.0) = x}</li> 660 * <li>{@code pow((anything), NaN) = NaN}</li> 661 * <li>{@code pow(NaN, (anything except 0)) = NaN}</li> 662 * <li>{@code pow(+/-(|x| > 1), +infinity) = +infinity}</li> 663 * <li>{@code pow(+/-(|x| > 1), -infinity) = +0.0}</li> 664 * <li>{@code pow(+/-(|x| < 1), +infinity) = +0.0}</li> 665 * <li>{@code pow(+/-(|x| < 1), -infinity) = +infinity}</li> 666 * <li>{@code pow(+/-1.0 , +infinity) = NaN}</li> 667 * <li>{@code pow(+/-1.0 , -infinity) = NaN}</li> 668 * <li>{@code pow(+0.0, (+anything except 0, NaN)) = +0.0}</li> 669 * <li>{@code pow(-0.0, (+anything except 0, NaN, odd integer)) = +0.0}</li> 670 * <li>{@code pow(+0.0, (-anything except 0, NaN)) = +infinity}</li> 671 * <li>{@code pow(-0.0, (-anything except 0, NAN, odd integer))} {@code =} 672 * {@code +infinity}</li> 673 * <li>{@code pow(-0.0, (odd integer)) = -pow( +0 , (odd integer) )}</li> 674 * <li>{@code pow(+infinity, (+anything except 0, NaN)) = +infinity}</li> 675 * <li>{@code pow(+infinity, (-anything except 0, NaN)) = +0.0}</li> 676 * <li>{@code pow(-infinity, (anything)) = -pow(0, (-anything))}</li> 677 * <li>{@code pow((-anything), (integer))} {@code =} 678 * {@code pow(-1,(integer))*pow(+anything,integer)}</li> 679 * <li>{@code pow((-anything except 0 and infinity), (non-integer))} 680 * {@code =} {@code NAN}</li> 681 * </ul> 682 * 683 * @param x 684 * the base of the operation. 685 * @param y 686 * the exponent of the operation. 687 * @return {@code x} to the power of {@code y}. 688 */ pow(double x, double y)689 public static native double pow(double x, double y); 690 691 /** 692 * Returns a pseudo-random number between 0.0 (inclusive) and 1.0 693 * (exclusive). 694 * 695 * @return a pseudo-random number. 696 */ random()697 public static double random() { 698 return Math.random(); 699 } 700 701 /** 702 * Returns the double conversion of the result of rounding the argument to 703 * an integer. Tie breaks are rounded towards even. 704 * <p> 705 * Special cases: 706 * <ul> 707 * <li>{@code rint(+0.0) = +0.0}</li> 708 * <li>{@code rint(-0.0) = -0.0}</li> 709 * <li>{@code rint(+infinity) = +infinity}</li> 710 * <li>{@code rint(-infinity) = -infinity}</li> 711 * <li>{@code rint(NaN) = NaN}</li> 712 * </ul> 713 * 714 * @param d 715 * the value to be rounded. 716 * @return the closest integer to the argument (as a double). 717 */ rint(double d)718 public static native double rint(double d); 719 720 /** 721 * Returns the result of rounding the argument to an integer. The result is 722 * equivalent to {@code (long) Math.floor(d+0.5)}. 723 * <p> 724 * Special cases: 725 * <ul> 726 * <li>{@code round(+0.0) = +0.0}</li> 727 * <li>{@code round(-0.0) = +0.0}</li> 728 * <li>{@code round((anything > Long.MAX_VALUE) = Long.MAX_VALUE}</li> 729 * <li>{@code round((anything < Long.MIN_VALUE) = Long.MIN_VALUE}</li> 730 * <li>{@code round(+infinity) = Long.MAX_VALUE}</li> 731 * <li>{@code round(-infinity) = Long.MIN_VALUE}</li> 732 * <li>{@code round(NaN) = +0.0}</li> 733 * </ul> 734 * 735 * @param d 736 * the value to be rounded. 737 * @return the closest integer to the argument. 738 */ round(double d)739 public static long round(double d) { 740 return Math.round(d); 741 } 742 743 /** 744 * Returns the result of rounding the argument to an integer. The result is 745 * equivalent to {@code (int) Math.floor(f+0.5)}. 746 * <p> 747 * Special cases: 748 * <ul> 749 * <li>{@code round(+0.0) = +0.0}</li> 750 * <li>{@code round(-0.0) = +0.0}</li> 751 * <li>{@code round((anything > Integer.MAX_VALUE) = Integer.MAX_VALUE}</li> 752 * <li>{@code round((anything < Integer.MIN_VALUE) = Integer.MIN_VALUE}</li> 753 * <li>{@code round(+infinity) = Integer.MAX_VALUE}</li> 754 * <li>{@code round(-infinity) = Integer.MIN_VALUE}</li> 755 * <li>{@code round(NaN) = +0.0}</li> 756 * </ul> 757 * 758 * @param f 759 * the value to be rounded. 760 * @return the closest integer to the argument. 761 */ round(float f)762 public static int round(float f) { 763 return Math.round(f); 764 } 765 766 /** 767 * Returns the signum function of the argument. If the argument is less than 768 * zero, it returns -1.0. If the argument is greater than zero, 1.0 is 769 * returned. If the argument is either positive or negative zero, the 770 * argument is returned as result. 771 * <p> 772 * Special cases: 773 * <ul> 774 * <li>{@code signum(+0.0) = +0.0}</li> 775 * <li>{@code signum(-0.0) = -0.0}</li> 776 * <li>{@code signum(+infinity) = +1.0}</li> 777 * <li>{@code signum(-infinity) = -1.0}</li> 778 * <li>{@code signum(NaN) = NaN}</li> 779 * </ul> 780 * 781 * @param d 782 * the value whose signum has to be computed. 783 * @return the value of the signum function. 784 */ signum(double d)785 public static double signum(double d){ 786 return Math.signum(d); 787 } 788 789 /** 790 * Returns the signum function of the argument. If the argument is less than 791 * zero, it returns -1.0. If the argument is greater than zero, 1.0 is 792 * returned. If the argument is either positive or negative zero, the 793 * argument is returned as result. 794 * <p> 795 * Special cases: 796 * <ul> 797 * <li>{@code signum(+0.0) = +0.0}</li> 798 * <li>{@code signum(-0.0) = -0.0}</li> 799 * <li>{@code signum(+infinity) = +1.0}</li> 800 * <li>{@code signum(-infinity) = -1.0}</li> 801 * <li>{@code signum(NaN) = NaN}</li> 802 * </ul> 803 * 804 * @param f 805 * the value whose signum has to be computed. 806 * @return the value of the signum function. 807 */ signum(float f)808 public static float signum(float f){ 809 return Math.signum(f); 810 } 811 812 /** 813 * Returns the closest double approximation of the hyperbolic sine of the 814 * argument. 815 * <p> 816 * Special cases: 817 * <ul> 818 * <li>{@code sinh(+0.0) = +0.0}</li> 819 * <li>{@code sinh(-0.0) = -0.0}</li> 820 * <li>{@code sinh(+infinity) = +infinity}</li> 821 * <li>{@code sinh(-infinity) = -infinity}</li> 822 * <li>{@code sinh(NaN) = NaN}</li> 823 * </ul> 824 * 825 * @param d 826 * the value whose hyperbolic sine has to be computed. 827 * @return the hyperbolic sine of the argument. 828 */ sinh(double d)829 public static native double sinh(double d); 830 831 /** 832 * Returns the closest double approximation of the sine of the argument. 833 * <p> 834 * Special cases: 835 * <ul> 836 * <li>{@code sin(+0.0) = +0.0}</li> 837 * <li>{@code sin(-0.0) = -0.0}</li> 838 * <li>{@code sin(+infinity) = NaN}</li> 839 * <li>{@code sin(-infinity) = NaN}</li> 840 * <li>{@code sin(NaN) = NaN}</li> 841 * </ul> 842 * 843 * @param d 844 * the angle whose sin has to be computed, in radians. 845 * @return the sine of the argument. 846 */ sin(double d)847 public static native double sin(double d); 848 849 /** 850 * Returns the closest double approximation of the square root of the 851 * argument. 852 * <p> 853 * Special cases: 854 * <ul> 855 * <li>{@code sqrt(+0.0) = +0.0}</li> 856 * <li>{@code sqrt(-0.0) = -0.0}</li> 857 * <li>{@code sqrt( (anything < 0) ) = NaN}</li> 858 * <li>{@code sqrt(+infinity) = +infinity}</li> 859 * <li>{@code sqrt(NaN) = NaN}</li> 860 * </ul> 861 * 862 * @param d 863 * the value whose square root has to be computed. 864 * @return the square root of the argument. 865 */ sqrt(double d)866 public static native double sqrt(double d); 867 868 /** 869 * Returns the closest double approximation of the tangent of the argument. 870 * <p> 871 * Special cases: 872 * <ul> 873 * <li>{@code tan(+0.0) = +0.0}</li> 874 * <li>{@code tan(-0.0) = -0.0}</li> 875 * <li>{@code tan(+infinity) = NaN}</li> 876 * <li>{@code tan(-infinity) = NaN}</li> 877 * <li>{@code tan(NaN) = NaN}</li> 878 * </ul> 879 * 880 * @param d 881 * the angle whose tangent has to be computed, in radians. 882 * @return the tangent of the argument. 883 */ tan(double d)884 public static native double tan(double d); 885 886 /** 887 * Returns the closest double approximation of the hyperbolic tangent of the 888 * argument. The absolute value is always less than 1. 889 * <p> 890 * Special cases: 891 * <ul> 892 * <li>{@code tanh(+0.0) = +0.0}</li> 893 * <li>{@code tanh(-0.0) = -0.0}</li> 894 * <li>{@code tanh(+infinity) = +1.0}</li> 895 * <li>{@code tanh(-infinity) = -1.0}</li> 896 * <li>{@code tanh(NaN) = NaN}</li> 897 * </ul> 898 * 899 * @param d 900 * the value whose hyperbolic tangent has to be computed. 901 * @return the hyperbolic tangent of the argument 902 */ tanh(double d)903 public static native double tanh(double d); 904 905 /** 906 * Returns the measure in degrees of the supplied radian angle. The result 907 * is {@code angrad * 180 / pi}. 908 * <p> 909 * Special cases: 910 * <ul> 911 * <li>{@code toDegrees(+0.0) = +0.0}</li> 912 * <li>{@code toDegrees(-0.0) = -0.0}</li> 913 * <li>{@code toDegrees(+infinity) = +infinity}</li> 914 * <li>{@code toDegrees(-infinity) = -infinity}</li> 915 * <li>{@code toDegrees(NaN) = NaN}</li> 916 * </ul> 917 * 918 * @param angrad 919 * an angle in radians. 920 * @return the degree measure of the angle. 921 */ toDegrees(double angrad)922 public static double toDegrees(double angrad) { 923 return Math.toDegrees(angrad); 924 } 925 926 /** 927 * Returns the measure in radians of the supplied degree angle. The result 928 * is {@code angdeg / 180 * pi}. 929 * <p> 930 * Special cases: 931 * <ul> 932 * <li>{@code toRadians(+0.0) = +0.0}</li> 933 * <li>{@code toRadians(-0.0) = -0.0}</li> 934 * <li>{@code toRadians(+infinity) = +infinity}</li> 935 * <li>{@code toRadians(-infinity) = -infinity}</li> 936 * <li>{@code toRadians(NaN) = NaN}</li> 937 * </ul> 938 * 939 * @param angdeg 940 * an angle in degrees. 941 * @return the radian measure of the angle. 942 */ toRadians(double angdeg)943 public static double toRadians(double angdeg) { 944 return Math.toRadians(angdeg); 945 } 946 947 /** 948 * Returns the argument's ulp (unit in the last place). The size of a ulp of 949 * a double value is the positive distance between this value and the double 950 * value next larger in magnitude. For non-NaN {@code x}, 951 * {@code ulp(-x) == ulp(x)}. 952 * <p> 953 * Special cases: 954 * <ul> 955 * <li>{@code ulp(+0.0) = Double.MIN_VALUE}</li> 956 * <li>{@code ulp(-0.0) = Double.MIN_VALUE}</li> 957 * <li>{@code ulp(+infinity) = infinity}</li> 958 * <li>{@code ulp(-infinity) = infinity}</li> 959 * <li>{@code ulp(NaN) = NaN}</li> 960 * </ul> 961 * 962 * @param d 963 * the floating-point value to compute ulp of. 964 * @return the size of a ulp of the argument. 965 */ ulp(double d)966 public static double ulp(double d) { 967 // special cases 968 if (Double.isInfinite(d)) { 969 return Double.POSITIVE_INFINITY; 970 } else if (d == Double.MAX_VALUE || d == -Double.MAX_VALUE) { 971 return pow(2, 971); 972 } 973 d = Math.abs(d); 974 return nextafter(d, Double.MAX_VALUE) - d; 975 } 976 977 /** 978 * Returns the argument's ulp (unit in the last place). The size of a ulp of 979 * a float value is the positive distance between this value and the float 980 * value next larger in magnitude. For non-NaN {@code x}, 981 * {@code ulp(-x) == ulp(x)}. 982 * <p> 983 * Special cases: 984 * <ul> 985 * <li>{@code ulp(+0.0) = Float.MIN_VALUE}</li> 986 * <li>{@code ulp(-0.0) = Float.MIN_VALUE}</li> 987 * <li>{@code ulp(+infinity) = infinity}</li> 988 * <li>{@code ulp(-infinity) = infinity}</li> 989 * <li>{@code ulp(NaN) = NaN}</li> 990 * </ul> 991 * 992 * @param f 993 * the floating-point value to compute ulp of. 994 * @return the size of a ulp of the argument. 995 */ ulp(float f)996 public static float ulp(float f) { 997 // special cases 998 if (Float.isNaN(f)) { 999 return Float.NaN; 1000 } else if (Float.isInfinite(f)) { 1001 return Float.POSITIVE_INFINITY; 1002 } else if (f == Float.MAX_VALUE || f == -Float.MAX_VALUE) { 1003 return (float) pow(2, 104); 1004 } 1005 f = Math.abs(f); 1006 return nextafterf(f, Float.MAX_VALUE) - f; 1007 } 1008 nextafter(double x, double y)1009 private native static double nextafter(double x, double y); 1010 nextafterf(float x, float y)1011 private native static float nextafterf(float x, float y); 1012 1013 /** 1014 * Returns a double with the given magnitude and the sign of {@code sign}. 1015 * If {@code sign} is NaN, the sign of the result is positive. 1016 * @since 1.6 1017 */ copySign(double magnitude, double sign)1018 public static double copySign(double magnitude, double sign) { 1019 // We manually inline Double.isNaN here because the JIT can't do it yet. 1020 // With Double.isNaN: 236.3ns 1021 // With manual inline: 141.2ns 1022 // With no check (i.e. Math's behavior): 110.0ns 1023 // (Tested on a Nexus One.) 1024 long magnitudeBits = Double.doubleToRawLongBits(magnitude); 1025 long signBits = Double.doubleToRawLongBits((sign != sign) ? 1.0 : sign); 1026 magnitudeBits = (magnitudeBits & ~Double.SIGN_MASK) | (signBits & Double.SIGN_MASK); 1027 return Double.longBitsToDouble(magnitudeBits); 1028 } 1029 1030 /** 1031 * Returns a float with the given magnitude and the sign of {@code sign}. 1032 * If {@code sign} is NaN, the sign of the result is positive. 1033 * @since 1.6 1034 */ copySign(float magnitude, float sign)1035 public static float copySign(float magnitude, float sign) { 1036 // We manually inline Float.isNaN here because the JIT can't do it yet. 1037 // With Float.isNaN: 214.7ns 1038 // With manual inline: 112.3ns 1039 // With no check (i.e. Math's behavior): 93.1ns 1040 // (Tested on a Nexus One.) 1041 int magnitudeBits = Float.floatToRawIntBits(magnitude); 1042 int signBits = Float.floatToRawIntBits((sign != sign) ? 1.0f : sign); 1043 magnitudeBits = (magnitudeBits & ~Float.SIGN_MASK) | (signBits & Float.SIGN_MASK); 1044 return Float.intBitsToFloat(magnitudeBits); 1045 } 1046 1047 /** 1048 * Returns the exponent of float {@code f}. 1049 * @since 1.6 1050 */ getExponent(float f)1051 public static int getExponent(float f) { 1052 return Math.getExponent(f); 1053 } 1054 1055 /** 1056 * Returns the exponent of double {@code d}. 1057 * @since 1.6 1058 */ getExponent(double d)1059 public static int getExponent(double d){ 1060 return Math.getExponent(d); 1061 } 1062 1063 /** 1064 * Returns the next double after {@code start} in the given {@code direction}. 1065 * @since 1.6 1066 */ nextAfter(double start, double direction)1067 public static double nextAfter(double start, double direction) { 1068 if (start == 0 && direction == 0) { 1069 return direction; 1070 } 1071 return nextafter(start, direction); 1072 } 1073 1074 /** 1075 * Returns the next float after {@code start} in the given {@code direction}. 1076 * @since 1.6 1077 */ nextAfter(float start, double direction)1078 public static float nextAfter(float start, double direction) { 1079 return Math.nextAfter(start, direction); 1080 } 1081 1082 /** 1083 * Returns the next double larger than {@code d}. 1084 * @since 1.6 1085 */ nextUp(double d)1086 public static double nextUp(double d) { 1087 return Math.nextUp(d); 1088 } 1089 1090 /** 1091 * Returns the next float larger than {@code f}. 1092 * @since 1.6 1093 */ nextUp(float f)1094 public static float nextUp(float f) { 1095 return Math.nextUp(f); 1096 } 1097 1098 /** 1099 * Returns {@code d} * 2^{@code scaleFactor}. The result may be rounded. 1100 * @since 1.6 1101 */ scalb(double d, int scaleFactor)1102 public static double scalb(double d, int scaleFactor) { 1103 if (Double.isNaN(d) || Double.isInfinite(d) || d == 0) { 1104 return d; 1105 } 1106 // change double to long for calculation 1107 long bits = Double.doubleToLongBits(d); 1108 // the sign of the results must be the same of given d 1109 long sign = bits & Double.SIGN_MASK; 1110 // calculates the factor of the result 1111 long factor = (int) ((bits & Double.EXPONENT_MASK) >> Double.MANTISSA_BITS) 1112 - Double.EXPONENT_BIAS + scaleFactor; 1113 1114 // calculates the factor of sub-normal values 1115 int subNormalFactor = Long.numberOfLeadingZeros(bits & ~Double.SIGN_MASK) 1116 - Double.EXPONENT_BITS; 1117 if (subNormalFactor < 0) { 1118 // not sub-normal values 1119 subNormalFactor = 0; 1120 } 1121 if (Math.abs(d) < Double.MIN_NORMAL) { 1122 factor = factor - subNormalFactor; 1123 } 1124 if (factor > Double.MAX_EXPONENT) { 1125 return (d > 0 ? Double.POSITIVE_INFINITY : Double.NEGATIVE_INFINITY); 1126 } 1127 1128 long result; 1129 // if result is a sub-normal 1130 if (factor < -Double.EXPONENT_BIAS) { 1131 // the number of digits that shifts 1132 long digits = factor + Double.EXPONENT_BIAS + subNormalFactor; 1133 if (Math.abs(d) < Double.MIN_NORMAL) { 1134 // origin d is already sub-normal 1135 result = shiftLongBits(bits & Double.MANTISSA_MASK, digits); 1136 } else { 1137 // origin d is not sub-normal, change mantissa to sub-normal 1138 result = shiftLongBits(bits & Double.MANTISSA_MASK | 0x0010000000000000L, digits - 1); 1139 } 1140 } else { 1141 if (Math.abs(d) >= Double.MIN_NORMAL) { 1142 // common situation 1143 result = ((factor + Double.EXPONENT_BIAS) << Double.MANTISSA_BITS) 1144 | (bits & Double.MANTISSA_MASK); 1145 } else { 1146 // origin d is sub-normal, change mantissa to normal style 1147 result = ((factor + Double.EXPONENT_BIAS) << Double.MANTISSA_BITS) 1148 | ((bits << (subNormalFactor + 1)) & Double.MANTISSA_MASK); 1149 } 1150 } 1151 return Double.longBitsToDouble(result | sign); 1152 } 1153 1154 /** 1155 * Returns {@code d} * 2^{@code scaleFactor}. The result may be rounded. 1156 * @since 1.6 1157 */ scalb(float d, int scaleFactor)1158 public static float scalb(float d, int scaleFactor) { 1159 if (Float.isNaN(d) || Float.isInfinite(d) || d == 0) { 1160 return d; 1161 } 1162 int bits = Float.floatToIntBits(d); 1163 int sign = bits & Float.SIGN_MASK; 1164 int factor = ((bits & Float.EXPONENT_MASK) >> Float.MANTISSA_BITS) 1165 - Float.EXPONENT_BIAS + scaleFactor; 1166 // calculates the factor of sub-normal values 1167 int subNormalFactor = Integer.numberOfLeadingZeros(bits & ~Float.SIGN_MASK) 1168 - Float.EXPONENT_BITS; 1169 if (subNormalFactor < 0) { 1170 // not sub-normal values 1171 subNormalFactor = 0; 1172 } 1173 if (Math.abs(d) < Float.MIN_NORMAL) { 1174 factor = factor - subNormalFactor; 1175 } 1176 if (factor > Float.MAX_EXPONENT) { 1177 return (d > 0 ? Float.POSITIVE_INFINITY : Float.NEGATIVE_INFINITY); 1178 } 1179 1180 int result; 1181 // if result is a sub-normal 1182 if (factor < -Float.EXPONENT_BIAS) { 1183 // the number of digits that shifts 1184 int digits = factor + Float.EXPONENT_BIAS + subNormalFactor; 1185 if (Math.abs(d) < Float.MIN_NORMAL) { 1186 // origin d is already sub-normal 1187 result = shiftIntBits(bits & Float.MANTISSA_MASK, digits); 1188 } else { 1189 // origin d is not sub-normal, change mantissa to sub-normal 1190 result = shiftIntBits(bits & Float.MANTISSA_MASK | 0x00800000, digits - 1); 1191 } 1192 } else { 1193 if (Math.abs(d) >= Float.MIN_NORMAL) { 1194 // common situation 1195 result = ((factor + Float.EXPONENT_BIAS) << Float.MANTISSA_BITS) 1196 | (bits & Float.MANTISSA_MASK); 1197 } else { 1198 // origin d is sub-normal, change mantissa to normal style 1199 result = ((factor + Float.EXPONENT_BIAS) << Float.MANTISSA_BITS) 1200 | ((bits << (subNormalFactor + 1)) & Float.MANTISSA_MASK); 1201 } 1202 } 1203 return Float.intBitsToFloat(result | sign); 1204 } 1205 1206 // Shifts integer bits as float, if the digits is positive, left-shift; if 1207 // not, shift to right and calculate its carry. shiftIntBits(int bits, int digits)1208 private static int shiftIntBits(int bits, int digits) { 1209 if (digits > 0) { 1210 return bits << digits; 1211 } 1212 // change it to positive 1213 int absdigits = -digits; 1214 if (Integer.numberOfLeadingZeros(bits & ~Float.SIGN_MASK) <= (32 - absdigits)) { 1215 // some bits will remain after shifting, calculates its carry 1216 if ((((bits >> (absdigits - 1)) & 0x1) == 0) 1217 || Integer.numberOfTrailingZeros(bits) == (absdigits - 1)) { 1218 return bits >> absdigits; 1219 } 1220 return ((bits >> absdigits) + 1); 1221 } 1222 return 0; 1223 } 1224 1225 // Shifts long bits as double, if the digits is positive, left-shift; if 1226 // not, shift to right and calculate its carry. shiftLongBits(long bits, long digits)1227 private static long shiftLongBits(long bits, long digits) { 1228 if (digits > 0) { 1229 return bits << digits; 1230 } 1231 // change it to positive 1232 long absdigits = -digits; 1233 if (Long.numberOfLeadingZeros(bits & ~Double.SIGN_MASK) <= (64 - absdigits)) { 1234 // some bits will remain after shifting, calculates its carry 1235 if ((((bits >> (absdigits - 1)) & 0x1) == 0) 1236 || Long.numberOfTrailingZeros(bits) == (absdigits - 1)) { 1237 return bits >> absdigits; 1238 } 1239 return ((bits >> absdigits) + 1); 1240 } 1241 return 0; 1242 } 1243 } 1244