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