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