1 /* 2 * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.lang; 27 import java.util.Random; 28 import sun.misc.DoubleConsts; 29 30 /** 31 * The class {@code StrictMath} contains methods for performing basic 32 * numeric operations such as the elementary exponential, logarithm, 33 * square root, and trigonometric functions. 34 * 35 * <p>To help ensure portability of Java programs, the definitions of 36 * some of the numeric functions in this package require that they 37 * produce the same results as certain published algorithms. These 38 * algorithms are available from the well-known network library 39 * {@code netlib} as the package "Freely Distributable Math 40 * Library," <a 41 * href="ftp://ftp.netlib.org/fdlibm.tar">{@code fdlibm}</a>. These 42 * algorithms, which are written in the C programming language, are 43 * then to be understood as executed with all floating-point 44 * operations following the rules of Java floating-point arithmetic. 45 * 46 * <p>The Java math library is defined with respect to 47 * {@code fdlibm} version 5.3. Where {@code fdlibm} provides 48 * more than one definition for a function (such as 49 * {@code acos}), use the "IEEE 754 core function" version 50 * (residing in a file whose name begins with the letter 51 * {@code e}). The methods which require {@code fdlibm} 52 * semantics are {@code sin}, {@code cos}, {@code tan}, 53 * {@code asin}, {@code acos}, {@code atan}, 54 * {@code exp}, {@code log}, {@code log10}, 55 * {@code cbrt}, {@code atan2}, {@code pow}, 56 * {@code sinh}, {@code cosh}, {@code tanh}, 57 * {@code hypot}, {@code expm1}, and {@code log1p}. 58 * 59 * <p> 60 * The platform uses signed two's complement integer arithmetic with 61 * int and long primitive types. The developer should choose 62 * the primitive type to ensure that arithmetic operations consistently 63 * produce correct results, which in some cases means the operations 64 * will not overflow the range of values of the computation. 65 * The best practice is to choose the primitive type and algorithm to avoid 66 * overflow. In cases where the size is {@code int} or {@code long} and 67 * overflow errors need to be detected, the methods {@code addExact}, 68 * {@code subtractExact}, {@code multiplyExact}, and {@code toIntExact} 69 * throw an {@code ArithmeticException} when the results overflow. 70 * For other arithmetic operations such as divide, absolute value, 71 * increment, decrement, and negation overflow occurs only with 72 * a specific minimum or maximum value and should be checked against 73 * the minimum or maximum as appropriate. 74 * 75 * @author unascribed 76 * @author Joseph D. Darcy 77 * @since 1.3 78 */ 79 80 public final class StrictMath { 81 82 /** 83 * Don't let anyone instantiate this class. 84 */ 85 private StrictMath() {} 86 87 /** 88 * The {@code double} value that is closer than any other to 89 * <i>e</i>, the base of the natural logarithms. 90 */ 91 public static final double E = 2.7182818284590452354; 92 93 /** 94 * The {@code double} value that is closer than any other to 95 * <i>pi</i>, the ratio of the circumference of a circle to its 96 * diameter. 97 */ 98 public static final double PI = 3.14159265358979323846; 99 100 /** 101 * Constant by which to multiply an angular value in degrees to obtain an 102 * angular value in radians. 103 */ 104 private static final double DEGREES_TO_RADIANS = 0.017453292519943295; 105 106 /** 107 * Constant by which to multiply an angular value in radians to obtain an 108 * angular value in degrees. 109 */ 110 111 private static final double RADIANS_TO_DEGREES = 57.29577951308232; 112 113 /** 114 * Returns the trigonometric sine of an angle. Special cases: 115 * <ul><li>If the argument is NaN or an infinity, then the 116 * result is NaN. 117 * <li>If the argument is zero, then the result is a zero with the 118 * same sign as the argument.</ul> 119 * 120 * @param a an angle, in radians. 121 * @return the sine of the argument. 122 */ 123 public static native double sin(double a); 124 125 /** 126 * Returns the trigonometric cosine of an angle. Special cases: 127 * <ul><li>If the argument is NaN or an infinity, then the 128 * result is NaN.</ul> 129 * 130 * @param a an angle, in radians. 131 * @return the cosine of the argument. 132 */ 133 public static native double cos(double a); 134 135 /** 136 * Returns the trigonometric tangent of an angle. Special cases: 137 * <ul><li>If the argument is NaN or an infinity, then the result 138 * is NaN. 139 * <li>If the argument is zero, then the result is a zero with the 140 * same sign as the argument.</ul> 141 * 142 * @param a an angle, in radians. 143 * @return the tangent of the argument. 144 */ 145 public static native double tan(double a); 146 147 /** 148 * Returns the arc sine of a value; the returned angle is in the 149 * range -<i>pi</i>/2 through <i>pi</i>/2. Special cases: 150 * <ul><li>If the argument is NaN or its absolute value is greater 151 * than 1, then the result is NaN. 152 * <li>If the argument is zero, then the result is a zero with the 153 * same sign as the argument.</ul> 154 * 155 * @param a the value whose arc sine is to be returned. 156 * @return the arc sine of the argument. 157 */ 158 public static native double asin(double a); 159 160 /** 161 * Returns the arc cosine of a value; the returned angle is in the 162 * range 0.0 through <i>pi</i>. Special case: 163 * <ul><li>If the argument is NaN or its absolute value is greater 164 * than 1, then the result is NaN.</ul> 165 * 166 * @param a the value whose arc cosine is to be returned. 167 * @return the arc cosine of the argument. 168 */ 169 public static native double acos(double a); 170 171 /** 172 * Returns the arc tangent of a value; the returned angle is in the 173 * range -<i>pi</i>/2 through <i>pi</i>/2. Special cases: 174 * <ul><li>If the argument is NaN, then the result is NaN. 175 * <li>If the argument is zero, then the result is a zero with the 176 * same sign as the argument.</ul> 177 * 178 * @param a the value whose arc tangent is to be returned. 179 * @return the arc tangent of the argument. 180 */ 181 public static native double atan(double a); 182 183 /** 184 * Converts an angle measured in degrees to an approximately 185 * equivalent angle measured in radians. The conversion from 186 * degrees to radians is generally inexact. 187 * 188 * @param angdeg an angle, in degrees 189 * @return the measurement of the angle {@code angdeg} 190 * in radians. 191 */ 192 public static strictfp double toRadians(double angdeg) { 193 // Do not delegate to Math.toRadians(angdeg) because 194 // this method has the strictfp modifier. 195 return angdeg * DEGREES_TO_RADIANS; 196 } 197 198 /** 199 * Converts an angle measured in radians to an approximately 200 * equivalent angle measured in degrees. The conversion from 201 * radians to degrees is generally inexact; users should 202 * <i>not</i> expect {@code cos(toRadians(90.0))} to exactly 203 * equal {@code 0.0}. 204 * 205 * @param angrad an angle, in radians 206 * @return the measurement of the angle {@code angrad} 207 * in degrees. 208 */ 209 public static strictfp double toDegrees(double angrad) { 210 // Do not delegate to Math.toDegrees(angrad) because 211 // this method has the strictfp modifier. 212 return angrad * RADIANS_TO_DEGREES; 213 } 214 215 /** 216 * Returns Euler's number <i>e</i> raised to the power of a 217 * {@code double} value. Special cases: 218 * <ul><li>If the argument is NaN, the result is NaN. 219 * <li>If the argument is positive infinity, then the result is 220 * positive infinity. 221 * <li>If the argument is negative infinity, then the result is 222 * positive zero.</ul> 223 * 224 * @param a the exponent to raise <i>e</i> to. 225 * @return the value <i>e</i><sup>{@code a}</sup>, 226 * where <i>e</i> is the base of the natural logarithms. 227 */ 228 public static native double exp(double a); 229 230 /** 231 * Returns the natural logarithm (base <i>e</i>) of a {@code double} 232 * value. Special cases: 233 * <ul><li>If the argument is NaN or less than zero, then the result 234 * is NaN. 235 * <li>If the argument is positive infinity, then the result is 236 * positive infinity. 237 * <li>If the argument is positive zero or negative zero, then the 238 * result is negative infinity.</ul> 239 * 240 * @param a a value 241 * @return the value ln {@code a}, the natural logarithm of 242 * {@code a}. 243 */ 244 public static native double log(double a); 245 246 247 /** 248 * Returns the base 10 logarithm of a {@code double} value. 249 * Special cases: 250 * 251 * <ul><li>If the argument is NaN or less than zero, then the result 252 * is NaN. 253 * <li>If the argument is positive infinity, then the result is 254 * positive infinity. 255 * <li>If the argument is positive zero or negative zero, then the 256 * result is negative infinity. 257 * <li> If the argument is equal to 10<sup><i>n</i></sup> for 258 * integer <i>n</i>, then the result is <i>n</i>. 259 * </ul> 260 * 261 * @param a a value 262 * @return the base 10 logarithm of {@code a}. 263 * @since 1.5 264 */ 265 public static native double log10(double a); 266 267 /** 268 * Returns the correctly rounded positive square root of a 269 * {@code double} value. 270 * Special cases: 271 * <ul><li>If the argument is NaN or less than zero, then the result 272 * is NaN. 273 * <li>If the argument is positive infinity, then the result is positive 274 * infinity. 275 * <li>If the argument is positive zero or negative zero, then the 276 * result is the same as the argument.</ul> 277 * Otherwise, the result is the {@code double} value closest to 278 * the true mathematical square root of the argument value. 279 * 280 * @param a a value. 281 * @return the positive square root of {@code a}. 282 */ 283 public static native double sqrt(double a); 284 285 /** 286 * Returns the cube root of a {@code double} value. For 287 * positive finite {@code x}, {@code cbrt(-x) == 288 * -cbrt(x)}; that is, the cube root of a negative value is 289 * the negative of the cube root of that value's magnitude. 290 * Special cases: 291 * 292 * <ul> 293 * 294 * <li>If the argument is NaN, then the result is NaN. 295 * 296 * <li>If the argument is infinite, then the result is an infinity 297 * with the same sign as the argument. 298 * 299 * <li>If the argument is zero, then the result is a zero with the 300 * same sign as the argument. 301 * 302 * </ul> 303 * 304 * @param a a value. 305 * @return the cube root of {@code a}. 306 * @since 1.5 307 */ 308 public static native double cbrt(double a); 309 310 /** 311 * Computes the remainder operation on two arguments as prescribed 312 * by the IEEE 754 standard. 313 * The remainder value is mathematically equal to 314 * <code>f1 - f2</code> × <i>n</i>, 315 * where <i>n</i> is the mathematical integer closest to the exact 316 * mathematical value of the quotient {@code f1/f2}, and if two 317 * mathematical integers are equally close to {@code f1/f2}, 318 * then <i>n</i> is the integer that is even. If the remainder is 319 * zero, its sign is the same as the sign of the first argument. 320 * Special cases: 321 * <ul><li>If either argument is NaN, or the first argument is infinite, 322 * or the second argument is positive zero or negative zero, then the 323 * result is NaN. 324 * <li>If the first argument is finite and the second argument is 325 * infinite, then the result is the same as the first argument.</ul> 326 * 327 * @param f1 the dividend. 328 * @param f2 the divisor. 329 * @return the remainder when {@code f1} is divided by 330 * {@code f2}. 331 */ 332 public static native double IEEEremainder(double f1, double f2); 333 334 /** 335 * Returns the smallest (closest to negative infinity) 336 * {@code double} value that is greater than or equal to the 337 * argument and is equal to a mathematical integer. Special cases: 338 * <ul><li>If the argument value is already equal to a 339 * mathematical integer, then the result is the same as the 340 * argument. <li>If the argument is NaN or an infinity or 341 * positive zero or negative zero, then the result is the same as 342 * the argument. <li>If the argument value is less than zero but 343 * greater than -1.0, then the result is negative zero.</ul> Note 344 * that the value of {@code StrictMath.ceil(x)} is exactly the 345 * value of {@code -StrictMath.floor(-x)}. 346 * 347 * @param a a value. 348 * @return the smallest (closest to negative infinity) 349 * floating-point value that is greater than or equal to 350 * the argument and is equal to a mathematical integer. 351 */ 352 public static double ceil(double a) { 353 return floorOrCeil(a, -0.0, 1.0, 1.0); 354 } 355 356 /** 357 * Returns the largest (closest to positive infinity) 358 * {@code double} value that is less than or equal to the 359 * argument and is equal to a mathematical integer. Special cases: 360 * <ul><li>If the argument value is already equal to a 361 * mathematical integer, then the result is the same as the 362 * argument. <li>If the argument is NaN or an infinity or 363 * positive zero or negative zero, then the result is the same as 364 * the argument.</ul> 365 * 366 * @param a a value. 367 * @return the largest (closest to positive infinity) 368 * floating-point value that less than or equal to the argument 369 * and is equal to a mathematical integer. 370 */ 371 public static double floor(double a) { 372 return floorOrCeil(a, -1.0, 0.0, -1.0); 373 } 374 375 /** 376 * Internal method to share logic between floor and ceil. 377 * 378 * @param a the value to be floored or ceiled 379 * @param negativeBoundary result for values in (-1, 0) 380 * @param positiveBoundary result for values in (0, 1) 381 * @param increment value to add when the argument is non-integral 382 */ 383 private static double floorOrCeil(double a, 384 double negativeBoundary, 385 double positiveBoundary, 386 double sign) { 387 int exponent = Math.getExponent(a); 388 389 if (exponent < 0) { 390 /* 391 * Absolute value of argument is less than 1. 392 * floorOrceil(-0.0) => -0.0 393 * floorOrceil(+0.0) => +0.0 394 */ 395 return ((a == 0.0) ? a : 396 ( (a < 0.0) ? negativeBoundary : positiveBoundary) ); 397 } else if (exponent >= 52) { 398 /* 399 * Infinity, NaN, or a value so large it must be integral. 400 */ 401 return a; 402 } 403 // Else the argument is either an integral value already XOR it 404 // has to be rounded to one. 405 assert exponent >= 0 && exponent <= 51; 406 407 long doppel = Double.doubleToRawLongBits(a); 408 long mask = DoubleConsts.SIGNIF_BIT_MASK >> exponent; 409 410 if ( (mask & doppel) == 0L ) 411 return a; // integral value 412 else { 413 double result = Double.longBitsToDouble(doppel & (~mask)); 414 if (sign*a > 0.0) 415 result = result + sign; 416 return result; 417 } 418 } 419 420 /** 421 * Returns the {@code double} value that is closest in value 422 * to the argument and is equal to a mathematical integer. If two 423 * {@code double} values that are mathematical integers are 424 * equally close to the value of the argument, the result is the 425 * integer value that is even. Special cases: 426 * <ul><li>If the argument value is already equal to a mathematical 427 * integer, then the result is the same as the argument. 428 * <li>If the argument is NaN or an infinity or positive zero or negative 429 * zero, then the result is the same as the argument.</ul> 430 * 431 * @param a a value. 432 * @return the closest floating-point value to {@code a} that is 433 * equal to a mathematical integer. 434 * @author Joseph D. Darcy 435 */ 436 public static double rint(double a) { 437 /* 438 * If the absolute value of a is not less than 2^52, it 439 * is either a finite integer (the double format does not have 440 * enough significand bits for a number that large to have any 441 * fractional portion), an infinity, or a NaN. In any of 442 * these cases, rint of the argument is the argument. 443 * 444 * Otherwise, the sum (twoToThe52 + a ) will properly round 445 * away any fractional portion of a since ulp(twoToThe52) == 446 * 1.0; subtracting out twoToThe52 from this sum will then be 447 * exact and leave the rounded integer portion of a. 448 * 449 * This method does *not* need to be declared strictfp to get 450 * fully reproducible results. Whether or not a method is 451 * declared strictfp can only make a difference in the 452 * returned result if some operation would overflow or 453 * underflow with strictfp semantics. The operation 454 * (twoToThe52 + a ) cannot overflow since large values of a 455 * are screened out; the add cannot underflow since twoToThe52 456 * is too large. The subtraction ((twoToThe52 + a ) - 457 * twoToThe52) will be exact as discussed above and thus 458 * cannot overflow or meaningfully underflow. Finally, the 459 * last multiply in the return statement is by plus or minus 460 * 1.0, which is exact too. 461 */ 462 double twoToThe52 = (double)(1L << 52); // 2^52 463 double sign = Math.copySign(1.0, a); // preserve sign info 464 a = Math.abs(a); 465 466 if (a < twoToThe52) { // E_min <= ilogb(a) <= 51 467 a = ((twoToThe52 + a ) - twoToThe52); 468 } 469 470 return sign * a; // restore original sign 471 } 472 473 /** 474 * Returns the angle <i>theta</i> from the conversion of rectangular 475 * coordinates ({@code x}, {@code y}) to polar 476 * coordinates (r, <i>theta</i>). 477 * This method computes the phase <i>theta</i> by computing an arc tangent 478 * of {@code y/x} in the range of -<i>pi</i> to <i>pi</i>. Special 479 * cases: 480 * <ul><li>If either argument is NaN, then the result is NaN. 481 * <li>If the first argument is positive zero and the second argument 482 * is positive, or the first argument is positive and finite and the 483 * second argument is positive infinity, then the result is positive 484 * zero. 485 * <li>If the first argument is negative zero and the second argument 486 * is positive, or the first argument is negative and finite and the 487 * second argument is positive infinity, then the result is negative zero. 488 * <li>If the first argument is positive zero and the second argument 489 * is negative, or the first argument is positive and finite and the 490 * second argument is negative infinity, then the result is the 491 * {@code double} value closest to <i>pi</i>. 492 * <li>If the first argument is negative zero and the second argument 493 * is negative, or the first argument is negative and finite and the 494 * second argument is negative infinity, then the result is the 495 * {@code double} value closest to -<i>pi</i>. 496 * <li>If the first argument is positive and the second argument is 497 * positive zero or negative zero, or the first argument is positive 498 * infinity and the second argument is finite, then the result is the 499 * {@code double} value closest to <i>pi</i>/2. 500 * <li>If the first argument is negative and the second argument is 501 * positive zero or negative zero, or the first argument is negative 502 * infinity and the second argument is finite, then the result is the 503 * {@code double} value closest to -<i>pi</i>/2. 504 * <li>If both arguments are positive infinity, then the result is the 505 * {@code double} value closest to <i>pi</i>/4. 506 * <li>If the first argument is positive infinity and the second argument 507 * is negative infinity, then the result is the {@code double} 508 * value closest to 3*<i>pi</i>/4. 509 * <li>If the first argument is negative infinity and the second argument 510 * is positive infinity, then the result is the {@code double} value 511 * closest to -<i>pi</i>/4. 512 * <li>If both arguments are negative infinity, then the result is the 513 * {@code double} value closest to -3*<i>pi</i>/4.</ul> 514 * 515 * @param y the ordinate coordinate 516 * @param x the abscissa coordinate 517 * @return the <i>theta</i> component of the point 518 * (<i>r</i>, <i>theta</i>) 519 * in polar coordinates that corresponds to the point 520 * (<i>x</i>, <i>y</i>) in Cartesian coordinates. 521 */ 522 public static native double atan2(double y, double x); 523 524 525 /** 526 * Returns the value of the first argument raised to the power of the 527 * second argument. Special cases: 528 * 529 * <ul><li>If the second argument is positive or negative zero, then the 530 * result is 1.0. 531 * <li>If the second argument is 1.0, then the result is the same as the 532 * first argument. 533 * <li>If the second argument is NaN, then the result is NaN. 534 * <li>If the first argument is NaN and the second argument is nonzero, 535 * then the result is NaN. 536 * 537 * <li>If 538 * <ul> 539 * <li>the absolute value of the first argument is greater than 1 540 * and the second argument is positive infinity, or 541 * <li>the absolute value of the first argument is less than 1 and 542 * the second argument is negative infinity, 543 * </ul> 544 * then the result is positive infinity. 545 * 546 * <li>If 547 * <ul> 548 * <li>the absolute value of the first argument is greater than 1 and 549 * the second argument is negative infinity, or 550 * <li>the absolute value of the 551 * first argument is less than 1 and the second argument is positive 552 * infinity, 553 * </ul> 554 * then the result is positive zero. 555 * 556 * <li>If the absolute value of the first argument equals 1 and the 557 * second argument is infinite, then the result is NaN. 558 * 559 * <li>If 560 * <ul> 561 * <li>the first argument is positive zero and the second argument 562 * is greater than zero, or 563 * <li>the first argument is positive infinity and the second 564 * argument is less than zero, 565 * </ul> 566 * then the result is positive zero. 567 * 568 * <li>If 569 * <ul> 570 * <li>the first argument is positive zero and the second argument 571 * is less than zero, or 572 * <li>the first argument is positive infinity and the second 573 * argument is greater than zero, 574 * </ul> 575 * then the result is positive infinity. 576 * 577 * <li>If 578 * <ul> 579 * <li>the first argument is negative zero and the second argument 580 * is greater than zero but not a finite odd integer, or 581 * <li>the first argument is negative infinity and the second 582 * argument is less than zero but not a finite odd integer, 583 * </ul> 584 * then the result is positive zero. 585 * 586 * <li>If 587 * <ul> 588 * <li>the first argument is negative zero and the second argument 589 * is a positive finite odd integer, or 590 * <li>the first argument is negative infinity and the second 591 * argument is a negative finite odd integer, 592 * </ul> 593 * then the result is negative zero. 594 * 595 * <li>If 596 * <ul> 597 * <li>the first argument is negative zero and the second argument 598 * is less than zero but not a finite odd integer, or 599 * <li>the first argument is negative infinity and the second 600 * argument is greater than zero but not a finite odd integer, 601 * </ul> 602 * then the result is positive infinity. 603 * 604 * <li>If 605 * <ul> 606 * <li>the first argument is negative zero and the second argument 607 * is a negative finite odd integer, or 608 * <li>the first argument is negative infinity and the second 609 * argument is a positive finite odd integer, 610 * </ul> 611 * then the result is negative infinity. 612 * 613 * <li>If the first argument is finite and less than zero 614 * <ul> 615 * <li> if the second argument is a finite even integer, the 616 * result is equal to the result of raising the absolute value of 617 * the first argument to the power of the second argument 618 * 619 * <li>if the second argument is a finite odd integer, the result 620 * is equal to the negative of the result of raising the absolute 621 * value of the first argument to the power of the second 622 * argument 623 * 624 * <li>if the second argument is finite and not an integer, then 625 * the result is NaN. 626 * </ul> 627 * 628 * <li>If both arguments are integers, then the result is exactly equal 629 * to the mathematical result of raising the first argument to the power 630 * of the second argument if that result can in fact be represented 631 * exactly as a {@code double} value.</ul> 632 * 633 * <p>(In the foregoing descriptions, a floating-point value is 634 * considered to be an integer if and only if it is finite and a 635 * fixed point of the method {@link #ceil ceil} or, 636 * equivalently, a fixed point of the method {@link #floor 637 * floor}. A value is a fixed point of a one-argument 638 * method if and only if the result of applying the method to the 639 * value is equal to the value.) 640 * 641 * @param a base. 642 * @param b the exponent. 643 * @return the value {@code a}<sup>{@code b}</sup>. 644 */ 645 public static native double pow(double a, double b); 646 647 /** 648 * Returns the closest {@code int} to the argument, with ties 649 * rounding to positive infinity. 650 * 651 * <p>Special cases: 652 * <ul><li>If the argument is NaN, the result is 0. 653 * <li>If the argument is negative infinity or any value less than or 654 * equal to the value of {@code Integer.MIN_VALUE}, the result is 655 * equal to the value of {@code Integer.MIN_VALUE}. 656 * <li>If the argument is positive infinity or any value greater than or 657 * equal to the value of {@code Integer.MAX_VALUE}, the result is 658 * equal to the value of {@code Integer.MAX_VALUE}.</ul> 659 * 660 * @param a a floating-point value to be rounded to an integer. 661 * @return the value of the argument rounded to the nearest 662 * {@code int} value. 663 * @see java.lang.Integer#MAX_VALUE 664 * @see java.lang.Integer#MIN_VALUE 665 */ 666 public static int round(float a) { 667 return Math.round(a); 668 } 669 670 /** 671 * Returns the closest {@code long} to the argument, with ties 672 * rounding to positive infinity. 673 * 674 * <p>Special cases: 675 * <ul><li>If the argument is NaN, the result is 0. 676 * <li>If the argument is negative infinity or any value less than or 677 * equal to the value of {@code Long.MIN_VALUE}, the result is 678 * equal to the value of {@code Long.MIN_VALUE}. 679 * <li>If the argument is positive infinity or any value greater than or 680 * equal to the value of {@code Long.MAX_VALUE}, the result is 681 * equal to the value of {@code Long.MAX_VALUE}.</ul> 682 * 683 * @param a a floating-point value to be rounded to a 684 * {@code long}. 685 * @return the value of the argument rounded to the nearest 686 * {@code long} value. 687 * @see java.lang.Long#MAX_VALUE 688 * @see java.lang.Long#MIN_VALUE 689 */ 690 public static long round(double a) { 691 return Math.round(a); 692 } 693 694 private static final class RandomNumberGeneratorHolder { 695 static final Random randomNumberGenerator = new Random(); 696 } 697 698 /** 699 * Returns a {@code double} value with a positive sign, greater 700 * than or equal to {@code 0.0} and less than {@code 1.0}. 701 * Returned values are chosen pseudorandomly with (approximately) 702 * uniform distribution from that range. 703 * 704 * <p>When this method is first called, it creates a single new 705 * pseudorandom-number generator, exactly as if by the expression 706 * 707 * <blockquote>{@code new java.util.Random()}</blockquote> 708 * 709 * This new pseudorandom-number generator is used thereafter for 710 * all calls to this method and is used nowhere else. 711 * 712 * <p>This method is properly synchronized to allow correct use by 713 * more than one thread. However, if many threads need to generate 714 * pseudorandom numbers at a great rate, it may reduce contention 715 * for each thread to have its own pseudorandom-number generator. 716 * 717 * @return a pseudorandom {@code double} greater than or equal 718 * to {@code 0.0} and less than {@code 1.0}. 719 * @see Random#nextDouble() 720 */ 721 public static double random() { 722 return RandomNumberGeneratorHolder.randomNumberGenerator.nextDouble(); 723 } 724 725 /** 726 * Returns the sum of its arguments, 727 * throwing an exception if the result overflows an {@code int}. 728 * 729 * @param x the first value 730 * @param y the second value 731 * @return the result 732 * @throws ArithmeticException if the result overflows an int 733 * @see Math#addExact(int,int) 734 * @since 1.8 735 */ 736 public static int addExact(int x, int y) { 737 return Math.addExact(x, y); 738 } 739 740 /** 741 * Returns the sum of its arguments, 742 * throwing an exception if the result overflows a {@code long}. 743 * 744 * @param x the first value 745 * @param y the second value 746 * @return the result 747 * @throws ArithmeticException if the result overflows a long 748 * @see Math#addExact(long,long) 749 * @since 1.8 750 */ 751 public static long addExact(long x, long y) { 752 return Math.addExact(x, y); 753 } 754 755 /** 756 * Returns the difference of the arguments, 757 * throwing an exception if the result overflows an {@code int}. 758 * 759 * @param x the first value 760 * @param y the second value to subtract from the first 761 * @return the result 762 * @throws ArithmeticException if the result overflows an int 763 * @see Math#subtractExact(int,int) 764 * @since 1.8 765 */ 766 public static int subtractExact(int x, int y) { 767 return Math.subtractExact(x, y); 768 } 769 770 /** 771 * Returns the difference of the arguments, 772 * throwing an exception if the result overflows a {@code long}. 773 * 774 * @param x the first value 775 * @param y the second value to subtract from the first 776 * @return the result 777 * @throws ArithmeticException if the result overflows a long 778 * @see Math#subtractExact(long,long) 779 * @since 1.8 780 */ 781 public static long subtractExact(long x, long y) { 782 return Math.subtractExact(x, y); 783 } 784 785 /** 786 * Returns the product of the arguments, 787 * throwing an exception if the result overflows an {@code int}. 788 * 789 * @param x the first value 790 * @param y the second value 791 * @return the result 792 * @throws ArithmeticException if the result overflows an int 793 * @see Math#multiplyExact(int,int) 794 * @since 1.8 795 */ 796 public static int multiplyExact(int x, int y) { 797 return Math.multiplyExact(x, y); 798 } 799 800 /** 801 * Returns the product of the arguments, 802 * throwing an exception if the result overflows a {@code long}. 803 * 804 * @param x the first value 805 * @param y the second value 806 * @return the result 807 * @throws ArithmeticException if the result overflows a long 808 * @see Math#multiplyExact(long,long) 809 * @since 1.8 810 */ 811 public static long multiplyExact(long x, long y) { 812 return Math.multiplyExact(x, y); 813 } 814 815 /** 816 * Returns the value of the {@code long} argument; 817 * throwing an exception if the value overflows an {@code int}. 818 * 819 * @param value the long value 820 * @return the argument as an int 821 * @throws ArithmeticException if the {@code argument} overflows an int 822 * @see Math#toIntExact(long) 823 * @since 1.8 824 */ 825 public static int toIntExact(long value) { 826 return Math.toIntExact(value); 827 } 828 829 /** 830 * Returns the largest (closest to positive infinity) 831 * {@code int} value that is less than or equal to the algebraic quotient. 832 * There is one special case, if the dividend is the 833 * {@linkplain Integer#MIN_VALUE Integer.MIN_VALUE} and the divisor is {@code -1}, 834 * then integer overflow occurs and 835 * the result is equal to the {@code Integer.MIN_VALUE}. 836 * <p> 837 * See {@link Math#floorDiv(int, int) Math.floorDiv} for examples and 838 * a comparison to the integer division {@code /} operator. 839 * 840 * @param x the dividend 841 * @param y the divisor 842 * @return the largest (closest to positive infinity) 843 * {@code int} value that is less than or equal to the algebraic quotient. 844 * @throws ArithmeticException if the divisor {@code y} is zero 845 * @see Math#floorDiv(int, int) 846 * @see Math#floor(double) 847 * @since 1.8 848 */ 849 public static int floorDiv(int x, int y) { 850 return Math.floorDiv(x, y); 851 } 852 853 /** 854 * Returns the largest (closest to positive infinity) 855 * {@code long} value that is less than or equal to the algebraic quotient. 856 * There is one special case, if the dividend is the 857 * {@linkplain Long#MIN_VALUE Long.MIN_VALUE} and the divisor is {@code -1}, 858 * then integer overflow occurs and 859 * the result is equal to the {@code Long.MIN_VALUE}. 860 * <p> 861 * See {@link Math#floorDiv(int, int) Math.floorDiv} for examples and 862 * a comparison to the integer division {@code /} operator. 863 * 864 * @param x the dividend 865 * @param y the divisor 866 * @return the largest (closest to positive infinity) 867 * {@code long} value that is less than or equal to the algebraic quotient. 868 * @throws ArithmeticException if the divisor {@code y} is zero 869 * @see Math#floorDiv(long, long) 870 * @see Math#floor(double) 871 * @since 1.8 872 */ 873 public static long floorDiv(long x, long y) { 874 return Math.floorDiv(x, y); 875 } 876 877 /** 878 * Returns the floor modulus of the {@code int} arguments. 879 * <p> 880 * The floor modulus is {@code x - (floorDiv(x, y) * y)}, 881 * has the same sign as the divisor {@code y}, and 882 * is in the range of {@code -abs(y) < r < +abs(y)}. 883 * <p> 884 * The relationship between {@code floorDiv} and {@code floorMod} is such that: 885 * <ul> 886 * <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x} 887 * </ul> 888 * <p> 889 * See {@link Math#floorMod(int, int) Math.floorMod} for examples and 890 * a comparison to the {@code %} operator. 891 * 892 * @param x the dividend 893 * @param y the divisor 894 * @return the floor modulus {@code x - (floorDiv(x, y) * y)} 895 * @throws ArithmeticException if the divisor {@code y} is zero 896 * @see Math#floorMod(int, int) 897 * @see StrictMath#floorDiv(int, int) 898 * @since 1.8 899 */ 900 public static int floorMod(int x, int y) { 901 return Math.floorMod(x , y); 902 } 903 /** 904 * Returns the floor modulus of the {@code long} arguments. 905 * <p> 906 * The floor modulus is {@code x - (floorDiv(x, y) * y)}, 907 * has the same sign as the divisor {@code y}, and 908 * is in the range of {@code -abs(y) < r < +abs(y)}. 909 * <p> 910 * The relationship between {@code floorDiv} and {@code floorMod} is such that: 911 * <ul> 912 * <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x} 913 * </ul> 914 * <p> 915 * See {@link Math#floorMod(int, int) Math.floorMod} for examples and 916 * a comparison to the {@code %} operator. 917 * 918 * @param x the dividend 919 * @param y the divisor 920 * @return the floor modulus {@code x - (floorDiv(x, y) * y)} 921 * @throws ArithmeticException if the divisor {@code y} is zero 922 * @see Math#floorMod(long, long) 923 * @see StrictMath#floorDiv(long, long) 924 * @since 1.8 925 */ 926 public static long floorMod(long x, long y) { 927 return Math.floorMod(x, y); 928 } 929 930 /** 931 * Returns the absolute value of an {@code int} value. 932 * If the argument is not negative, the argument is returned. 933 * If the argument is negative, the negation of the argument is returned. 934 * 935 * <p>Note that if the argument is equal to the value of 936 * {@link Integer#MIN_VALUE}, the most negative representable 937 * {@code int} value, the result is that same value, which is 938 * negative. 939 * 940 * @param a the argument whose absolute value is to be determined. 941 * @return the absolute value of the argument. 942 */ 943 public static int abs(int a) { 944 return Math.abs(a); 945 } 946 947 /** 948 * Returns the absolute value of a {@code long} value. 949 * If the argument is not negative, the argument is returned. 950 * If the argument is negative, the negation of the argument is returned. 951 * 952 * <p>Note that if the argument is equal to the value of 953 * {@link Long#MIN_VALUE}, the most negative representable 954 * {@code long} value, the result is that same value, which 955 * is negative. 956 * 957 * @param a the argument whose absolute value is to be determined. 958 * @return the absolute value of the argument. 959 */ 960 public static long abs(long a) { 961 return Math.abs(a); 962 } 963 964 /** 965 * Returns the absolute value of a {@code float} value. 966 * If the argument is not negative, the argument is returned. 967 * If the argument is negative, the negation of the argument is returned. 968 * Special cases: 969 * <ul><li>If the argument is positive zero or negative zero, the 970 * result is positive zero. 971 * <li>If the argument is infinite, the result is positive infinity. 972 * <li>If the argument is NaN, the result is NaN.</ul> 973 * In other words, the result is the same as the value of the expression: 974 * <p>{@code Float.intBitsToFloat(0x7fffffff & Float.floatToIntBits(a))} 975 * 976 * @param a the argument whose absolute value is to be determined 977 * @return the absolute value of the argument. 978 */ 979 public static float abs(float a) { 980 return Math.abs(a); 981 } 982 983 /** 984 * Returns the absolute value of a {@code double} value. 985 * If the argument is not negative, the argument is returned. 986 * If the argument is negative, the negation of the argument is returned. 987 * Special cases: 988 * <ul><li>If the argument is positive zero or negative zero, the result 989 * is positive zero. 990 * <li>If the argument is infinite, the result is positive infinity. 991 * <li>If the argument is NaN, the result is NaN.</ul> 992 * In other words, the result is the same as the value of the expression: 993 * <p>{@code Double.longBitsToDouble((Double.doubleToLongBits(a)<<1)>>>1)} 994 * 995 * @param a the argument whose absolute value is to be determined 996 * @return the absolute value of the argument. 997 */ 998 public static double abs(double a) { 999 return Math.abs(a); 1000 } 1001 1002 /** 1003 * Returns the greater of two {@code int} values. That is, the 1004 * result is the argument closer to the value of 1005 * {@link Integer#MAX_VALUE}. If the arguments have the same value, 1006 * the result is that same value. 1007 * 1008 * @param a an argument. 1009 * @param b another argument. 1010 * @return the larger of {@code a} and {@code b}. 1011 */ 1012 public static int max(int a, int b) { 1013 return Math.max(a, b); 1014 } 1015 1016 /** 1017 * Returns the greater of two {@code long} values. That is, the 1018 * result is the argument closer to the value of 1019 * {@link Long#MAX_VALUE}. If the arguments have the same value, 1020 * the result is that same value. 1021 * 1022 * @param a an argument. 1023 * @param b another argument. 1024 * @return the larger of {@code a} and {@code b}. 1025 */ 1026 public static long max(long a, long b) { 1027 return Math.max(a, b); 1028 } 1029 1030 /** 1031 * Returns the greater of two {@code float} values. That is, 1032 * the result is the argument closer to positive infinity. If the 1033 * arguments have the same value, the result is that same 1034 * value. If either value is NaN, then the result is NaN. Unlike 1035 * the numerical comparison operators, this method considers 1036 * negative zero to be strictly smaller than positive zero. If one 1037 * argument is positive zero and the other negative zero, the 1038 * result is positive zero. 1039 * 1040 * @param a an argument. 1041 * @param b another argument. 1042 * @return the larger of {@code a} and {@code b}. 1043 */ 1044 public static float max(float a, float b) { 1045 return Math.max(a, b); 1046 } 1047 1048 /** 1049 * Returns the greater of two {@code double} values. That 1050 * is, the result is the argument closer to positive infinity. If 1051 * the arguments have the same value, the result is that same 1052 * value. If either value is NaN, then the result is NaN. Unlike 1053 * the numerical comparison operators, this method considers 1054 * negative zero to be strictly smaller than positive zero. If one 1055 * argument is positive zero and the other negative zero, the 1056 * result is positive zero. 1057 * 1058 * @param a an argument. 1059 * @param b another argument. 1060 * @return the larger of {@code a} and {@code b}. 1061 */ 1062 public static double max(double a, double b) { 1063 return Math.max(a, b); 1064 } 1065 1066 /** 1067 * Returns the smaller of two {@code int} values. That is, 1068 * the result the argument closer to the value of 1069 * {@link Integer#MIN_VALUE}. If the arguments have the same 1070 * value, the result is that same value. 1071 * 1072 * @param a an argument. 1073 * @param b another argument. 1074 * @return the smaller of {@code a} and {@code b}. 1075 */ 1076 public static int min(int a, int b) { 1077 return Math.min(a, b); 1078 } 1079 1080 /** 1081 * Returns the smaller of two {@code long} values. That is, 1082 * the result is the argument closer to the value of 1083 * {@link Long#MIN_VALUE}. If the arguments have the same 1084 * value, the result is that same value. 1085 * 1086 * @param a an argument. 1087 * @param b another argument. 1088 * @return the smaller of {@code a} and {@code b}. 1089 */ 1090 public static long min(long a, long b) { 1091 return Math.min(a, b); 1092 } 1093 1094 /** 1095 * Returns the smaller of two {@code float} values. That is, 1096 * the result is the value closer to negative infinity. If the 1097 * arguments have the same value, the result is that same 1098 * value. If either value is NaN, then the result is NaN. Unlike 1099 * the numerical comparison operators, this method considers 1100 * negative zero to be strictly smaller than positive zero. If 1101 * one argument is positive zero and the other is negative zero, 1102 * the result is negative zero. 1103 * 1104 * @param a an argument. 1105 * @param b another argument. 1106 * @return the smaller of {@code a} and {@code b.} 1107 */ 1108 public static float min(float a, float b) { 1109 return Math.min(a, b); 1110 } 1111 1112 /** 1113 * Returns the smaller of two {@code double} values. That 1114 * is, the result is the value closer to negative infinity. If the 1115 * arguments have the same value, the result is that same 1116 * value. If either value is NaN, then the result is NaN. Unlike 1117 * the numerical comparison operators, this method considers 1118 * negative zero to be strictly smaller than positive zero. If one 1119 * argument is positive zero and the other is negative zero, the 1120 * result is negative zero. 1121 * 1122 * @param a an argument. 1123 * @param b another argument. 1124 * @return the smaller of {@code a} and {@code b}. 1125 */ 1126 public static double min(double a, double b) { 1127 return Math.min(a, b); 1128 } 1129 1130 /** 1131 * Returns the size of an ulp of the argument. An ulp, unit in 1132 * the last place, of a {@code double} value is the positive 1133 * distance between this floating-point value and the {@code 1134 * double} value next larger in magnitude. Note that for non-NaN 1135 * <i>x</i>, <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>. 1136 * 1137 * <p>Special Cases: 1138 * <ul> 1139 * <li> If the argument is NaN, then the result is NaN. 1140 * <li> If the argument is positive or negative infinity, then the 1141 * result is positive infinity. 1142 * <li> If the argument is positive or negative zero, then the result is 1143 * {@code Double.MIN_VALUE}. 1144 * <li> If the argument is ±{@code Double.MAX_VALUE}, then 1145 * the result is equal to 2<sup>971</sup>. 1146 * </ul> 1147 * 1148 * @param d the floating-point value whose ulp is to be returned 1149 * @return the size of an ulp of the argument 1150 * @author Joseph D. Darcy 1151 * @since 1.5 1152 */ 1153 public static double ulp(double d) { 1154 return Math.ulp(d); 1155 } 1156 1157 /** 1158 * Returns the size of an ulp of the argument. An ulp, unit in 1159 * the last place, of a {@code float} value is the positive 1160 * distance between this floating-point value and the {@code 1161 * float} value next larger in magnitude. Note that for non-NaN 1162 * <i>x</i>, <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>. 1163 * 1164 * <p>Special Cases: 1165 * <ul> 1166 * <li> If the argument is NaN, then the result is NaN. 1167 * <li> If the argument is positive or negative infinity, then the 1168 * result is positive infinity. 1169 * <li> If the argument is positive or negative zero, then the result is 1170 * {@code Float.MIN_VALUE}. 1171 * <li> If the argument is ±{@code Float.MAX_VALUE}, then 1172 * the result is equal to 2<sup>104</sup>. 1173 * </ul> 1174 * 1175 * @param f the floating-point value whose ulp is to be returned 1176 * @return the size of an ulp of the argument 1177 * @author Joseph D. Darcy 1178 * @since 1.5 1179 */ 1180 public static float ulp(float f) { 1181 return Math.ulp(f); 1182 } 1183 1184 /** 1185 * Returns the signum function of the argument; zero if the argument 1186 * is zero, 1.0 if the argument is greater than zero, -1.0 if the 1187 * argument is less than zero. 1188 * 1189 * <p>Special Cases: 1190 * <ul> 1191 * <li> If the argument is NaN, then the result is NaN. 1192 * <li> If the argument is positive zero or negative zero, then the 1193 * result is the same as the argument. 1194 * </ul> 1195 * 1196 * @param d the floating-point value whose signum is to be returned 1197 * @return the signum function of the argument 1198 * @author Joseph D. Darcy 1199 * @since 1.5 1200 */ 1201 public static double signum(double d) { 1202 return Math.signum(d); 1203 } 1204 1205 /** 1206 * Returns the signum function of the argument; zero if the argument 1207 * is zero, 1.0f if the argument is greater than zero, -1.0f if the 1208 * argument is less than zero. 1209 * 1210 * <p>Special Cases: 1211 * <ul> 1212 * <li> If the argument is NaN, then the result is NaN. 1213 * <li> If the argument is positive zero or negative zero, then the 1214 * result is the same as the argument. 1215 * </ul> 1216 * 1217 * @param f the floating-point value whose signum is to be returned 1218 * @return the signum function of the argument 1219 * @author Joseph D. Darcy 1220 * @since 1.5 1221 */ 1222 public static float signum(float f) { 1223 return Math.signum(f); 1224 } 1225 1226 /** 1227 * Returns the hyperbolic sine of a {@code double} value. 1228 * The hyperbolic sine of <i>x</i> is defined to be 1229 * (<i>e<sup>x</sup> - e<sup>-x</sup></i>)/2 1230 * where <i>e</i> is {@linkplain Math#E Euler's number}. 1231 * 1232 * <p>Special cases: 1233 * <ul> 1234 * 1235 * <li>If the argument is NaN, then the result is NaN. 1236 * 1237 * <li>If the argument is infinite, then the result is an infinity 1238 * with the same sign as the argument. 1239 * 1240 * <li>If the argument is zero, then the result is a zero with the 1241 * same sign as the argument. 1242 * 1243 * </ul> 1244 * 1245 * @param x The number whose hyperbolic sine is to be returned. 1246 * @return The hyperbolic sine of {@code x}. 1247 * @since 1.5 1248 */ 1249 public static native double sinh(double x); 1250 1251 /** 1252 * Returns the hyperbolic cosine of a {@code double} value. 1253 * The hyperbolic cosine of <i>x</i> is defined to be 1254 * (<i>e<sup>x</sup> + e<sup>-x</sup></i>)/2 1255 * where <i>e</i> is {@linkplain Math#E Euler's number}. 1256 * 1257 * <p>Special cases: 1258 * <ul> 1259 * 1260 * <li>If the argument is NaN, then the result is NaN. 1261 * 1262 * <li>If the argument is infinite, then the result is positive 1263 * infinity. 1264 * 1265 * <li>If the argument is zero, then the result is {@code 1.0}. 1266 * 1267 * </ul> 1268 * 1269 * @param x The number whose hyperbolic cosine is to be returned. 1270 * @return The hyperbolic cosine of {@code x}. 1271 * @since 1.5 1272 */ 1273 public static native double cosh(double x); 1274 1275 /** 1276 * Returns the hyperbolic tangent of a {@code double} value. 1277 * The hyperbolic tangent of <i>x</i> is defined to be 1278 * (<i>e<sup>x</sup> - e<sup>-x</sup></i>)/(<i>e<sup>x</sup> + e<sup>-x</sup></i>), 1279 * in other words, {@linkplain Math#sinh 1280 * sinh(<i>x</i>)}/{@linkplain Math#cosh cosh(<i>x</i>)}. Note 1281 * that the absolute value of the exact tanh is always less than 1282 * 1. 1283 * 1284 * <p>Special cases: 1285 * <ul> 1286 * 1287 * <li>If the argument is NaN, then the result is NaN. 1288 * 1289 * <li>If the argument is zero, then the result is a zero with the 1290 * same sign as the argument. 1291 * 1292 * <li>If the argument is positive infinity, then the result is 1293 * {@code +1.0}. 1294 * 1295 * <li>If the argument is negative infinity, then the result is 1296 * {@code -1.0}. 1297 * 1298 * </ul> 1299 * 1300 * @param x The number whose hyperbolic tangent is to be returned. 1301 * @return The hyperbolic tangent of {@code x}. 1302 * @since 1.5 1303 */ 1304 public static native double tanh(double x); 1305 1306 /** 1307 * Returns sqrt(<i>x</i><sup>2</sup> +<i>y</i><sup>2</sup>) 1308 * without intermediate overflow or underflow. 1309 * 1310 * <p>Special cases: 1311 * <ul> 1312 * 1313 * <li> If either argument is infinite, then the result 1314 * is positive infinity. 1315 * 1316 * <li> If either argument is NaN and neither argument is infinite, 1317 * then the result is NaN. 1318 * 1319 * </ul> 1320 * 1321 * @param x a value 1322 * @param y a value 1323 * @return sqrt(<i>x</i><sup>2</sup> +<i>y</i><sup>2</sup>) 1324 * without intermediate overflow or underflow 1325 * @since 1.5 1326 */ 1327 public static native double hypot(double x, double y); 1328 1329 /** 1330 * Returns <i>e</i><sup>x</sup> -1. Note that for values of 1331 * <i>x</i> near 0, the exact sum of 1332 * {@code expm1(x)} + 1 is much closer to the true 1333 * result of <i>e</i><sup>x</sup> than {@code exp(x)}. 1334 * 1335 * <p>Special cases: 1336 * <ul> 1337 * <li>If the argument is NaN, the result is NaN. 1338 * 1339 * <li>If the argument is positive infinity, then the result is 1340 * positive infinity. 1341 * 1342 * <li>If the argument is negative infinity, then the result is 1343 * -1.0. 1344 * 1345 * <li>If the argument is zero, then the result is a zero with the 1346 * same sign as the argument. 1347 * 1348 * </ul> 1349 * 1350 * @param x the exponent to raise <i>e</i> to in the computation of 1351 * <i>e</i><sup>{@code x}</sup> -1. 1352 * @return the value <i>e</i><sup>{@code x}</sup> - 1. 1353 * @since 1.5 1354 */ 1355 public static native double expm1(double x); 1356 1357 /** 1358 * Returns the natural logarithm of the sum of the argument and 1. 1359 * Note that for small values {@code x}, the result of 1360 * {@code log1p(x)} is much closer to the true result of ln(1 1361 * + {@code x}) than the floating-point evaluation of 1362 * {@code log(1.0+x)}. 1363 * 1364 * <p>Special cases: 1365 * <ul> 1366 * 1367 * <li>If the argument is NaN or less than -1, then the result is 1368 * NaN. 1369 * 1370 * <li>If the argument is positive infinity, then the result is 1371 * positive infinity. 1372 * 1373 * <li>If the argument is negative one, then the result is 1374 * negative infinity. 1375 * 1376 * <li>If the argument is zero, then the result is a zero with the 1377 * same sign as the argument. 1378 * 1379 * </ul> 1380 * 1381 * @param x a value 1382 * @return the value ln({@code x} + 1), the natural 1383 * log of {@code x} + 1 1384 * @since 1.5 1385 */ 1386 public static native double log1p(double x); 1387 1388 /** 1389 * Returns the first floating-point argument with the sign of the 1390 * second floating-point argument. For this method, a NaN 1391 * {@code sign} argument is always treated as if it were 1392 * positive. 1393 * 1394 * @param magnitude the parameter providing the magnitude of the result 1395 * @param sign the parameter providing the sign of the result 1396 * @return a value with the magnitude of {@code magnitude} 1397 * and the sign of {@code sign}. 1398 * @since 1.6 1399 */ 1400 public static double copySign(double magnitude, double sign) { 1401 return Math.copySign(magnitude, (Double.isNaN(sign)?1.0d:sign)); 1402 } 1403 1404 /** 1405 * Returns the first floating-point argument with the sign of the 1406 * second floating-point argument. For this method, a NaN 1407 * {@code sign} argument is always treated as if it were 1408 * positive. 1409 * 1410 * @param magnitude the parameter providing the magnitude of the result 1411 * @param sign the parameter providing the sign of the result 1412 * @return a value with the magnitude of {@code magnitude} 1413 * and the sign of {@code sign}. 1414 * @since 1.6 1415 */ 1416 public static float copySign(float magnitude, float sign) { 1417 return Math.copySign(magnitude, (Float.isNaN(sign)?1.0f:sign)); 1418 } 1419 /** 1420 * Returns the unbiased exponent used in the representation of a 1421 * {@code float}. Special cases: 1422 * 1423 * <ul> 1424 * <li>If the argument is NaN or infinite, then the result is 1425 * {@link Float#MAX_EXPONENT} + 1. 1426 * <li>If the argument is zero or subnormal, then the result is 1427 * {@link Float#MIN_EXPONENT} -1. 1428 * </ul> 1429 * @param f a {@code float} value 1430 * @return the unbiased exponent of the argument 1431 * @since 1.6 1432 */ 1433 public static int getExponent(float f) { 1434 return Math.getExponent(f); 1435 } 1436 1437 /** 1438 * Returns the unbiased exponent used in the representation of a 1439 * {@code double}. Special cases: 1440 * 1441 * <ul> 1442 * <li>If the argument is NaN or infinite, then the result is 1443 * {@link Double#MAX_EXPONENT} + 1. 1444 * <li>If the argument is zero or subnormal, then the result is 1445 * {@link Double#MIN_EXPONENT} -1. 1446 * </ul> 1447 * @param d a {@code double} value 1448 * @return the unbiased exponent of the argument 1449 * @since 1.6 1450 */ 1451 public static int getExponent(double d) { 1452 return Math.getExponent(d); 1453 } 1454 1455 /** 1456 * Returns the floating-point number adjacent to the first 1457 * argument in the direction of the second argument. If both 1458 * arguments compare as equal the second argument is returned. 1459 * 1460 * <p>Special cases: 1461 * <ul> 1462 * <li> If either argument is a NaN, then NaN is returned. 1463 * 1464 * <li> If both arguments are signed zeros, {@code direction} 1465 * is returned unchanged (as implied by the requirement of 1466 * returning the second argument if the arguments compare as 1467 * equal). 1468 * 1469 * <li> If {@code start} is 1470 * ±{@link Double#MIN_VALUE} and {@code direction} 1471 * has a value such that the result should have a smaller 1472 * magnitude, then a zero with the same sign as {@code start} 1473 * is returned. 1474 * 1475 * <li> If {@code start} is infinite and 1476 * {@code direction} has a value such that the result should 1477 * have a smaller magnitude, {@link Double#MAX_VALUE} with the 1478 * same sign as {@code start} is returned. 1479 * 1480 * <li> If {@code start} is equal to ± 1481 * {@link Double#MAX_VALUE} and {@code direction} has a 1482 * value such that the result should have a larger magnitude, an 1483 * infinity with same sign as {@code start} is returned. 1484 * </ul> 1485 * 1486 * @param start starting floating-point value 1487 * @param direction value indicating which of 1488 * {@code start}'s neighbors or {@code start} should 1489 * be returned 1490 * @return The floating-point number adjacent to {@code start} in the 1491 * direction of {@code direction}. 1492 * @since 1.6 1493 */ 1494 public static double nextAfter(double start, double direction) { 1495 return Math.nextAfter(start, direction); 1496 } 1497 1498 /** 1499 * Returns the floating-point number adjacent to the first 1500 * argument in the direction of the second argument. If both 1501 * arguments compare as equal a value equivalent to the second argument 1502 * is returned. 1503 * 1504 * <p>Special cases: 1505 * <ul> 1506 * <li> If either argument is a NaN, then NaN is returned. 1507 * 1508 * <li> If both arguments are signed zeros, a value equivalent 1509 * to {@code direction} is returned. 1510 * 1511 * <li> If {@code start} is 1512 * ±{@link Float#MIN_VALUE} and {@code direction} 1513 * has a value such that the result should have a smaller 1514 * magnitude, then a zero with the same sign as {@code start} 1515 * is returned. 1516 * 1517 * <li> If {@code start} is infinite and 1518 * {@code direction} has a value such that the result should 1519 * have a smaller magnitude, {@link Float#MAX_VALUE} with the 1520 * same sign as {@code start} is returned. 1521 * 1522 * <li> If {@code start} is equal to ± 1523 * {@link Float#MAX_VALUE} and {@code direction} has a 1524 * value such that the result should have a larger magnitude, an 1525 * infinity with same sign as {@code start} is returned. 1526 * </ul> 1527 * 1528 * @param start starting floating-point value 1529 * @param direction value indicating which of 1530 * {@code start}'s neighbors or {@code start} should 1531 * be returned 1532 * @return The floating-point number adjacent to {@code start} in the 1533 * direction of {@code direction}. 1534 * @since 1.6 1535 */ 1536 public static float nextAfter(float start, double direction) { 1537 return Math.nextAfter(start, direction); 1538 } 1539 1540 /** 1541 * Returns the floating-point value adjacent to {@code d} in 1542 * the direction of positive infinity. This method is 1543 * semantically equivalent to {@code nextAfter(d, 1544 * Double.POSITIVE_INFINITY)}; however, a {@code nextUp} 1545 * implementation may run faster than its equivalent 1546 * {@code nextAfter} call. 1547 * 1548 * <p>Special Cases: 1549 * <ul> 1550 * <li> If the argument is NaN, the result is NaN. 1551 * 1552 * <li> If the argument is positive infinity, the result is 1553 * positive infinity. 1554 * 1555 * <li> If the argument is zero, the result is 1556 * {@link Double#MIN_VALUE} 1557 * 1558 * </ul> 1559 * 1560 * @param d starting floating-point value 1561 * @return The adjacent floating-point value closer to positive 1562 * infinity. 1563 * @since 1.6 1564 */ 1565 public static double nextUp(double d) { 1566 return Math.nextUp(d); 1567 } 1568 1569 /** 1570 * Returns the floating-point value adjacent to {@code f} in 1571 * the direction of positive infinity. This method is 1572 * semantically equivalent to {@code nextAfter(f, 1573 * Float.POSITIVE_INFINITY)}; however, a {@code nextUp} 1574 * implementation may run faster than its equivalent 1575 * {@code nextAfter} call. 1576 * 1577 * <p>Special Cases: 1578 * <ul> 1579 * <li> If the argument is NaN, the result is NaN. 1580 * 1581 * <li> If the argument is positive infinity, the result is 1582 * positive infinity. 1583 * 1584 * <li> If the argument is zero, the result is 1585 * {@link Float#MIN_VALUE} 1586 * 1587 * </ul> 1588 * 1589 * @param f starting floating-point value 1590 * @return The adjacent floating-point value closer to positive 1591 * infinity. 1592 * @since 1.6 1593 */ 1594 public static float nextUp(float f) { 1595 return Math.nextUp(f); 1596 } 1597 1598 /** 1599 * Returns the floating-point value adjacent to {@code d} in 1600 * the direction of negative infinity. This method is 1601 * semantically equivalent to {@code nextAfter(d, 1602 * Double.NEGATIVE_INFINITY)}; however, a 1603 * {@code nextDown} implementation may run faster than its 1604 * equivalent {@code nextAfter} call. 1605 * 1606 * <p>Special Cases: 1607 * <ul> 1608 * <li> If the argument is NaN, the result is NaN. 1609 * 1610 * <li> If the argument is negative infinity, the result is 1611 * negative infinity. 1612 * 1613 * <li> If the argument is zero, the result is 1614 * {@code -Double.MIN_VALUE} 1615 * 1616 * </ul> 1617 * 1618 * @param d starting floating-point value 1619 * @return The adjacent floating-point value closer to negative 1620 * infinity. 1621 * @since 1.8 1622 */ 1623 public static double nextDown(double d) { 1624 return Math.nextDown(d); 1625 } 1626 1627 /** 1628 * Returns the floating-point value adjacent to {@code f} in 1629 * the direction of negative infinity. This method is 1630 * semantically equivalent to {@code nextAfter(f, 1631 * Float.NEGATIVE_INFINITY)}; however, a 1632 * {@code nextDown} implementation may run faster than its 1633 * equivalent {@code nextAfter} call. 1634 * 1635 * <p>Special Cases: 1636 * <ul> 1637 * <li> If the argument is NaN, the result is NaN. 1638 * 1639 * <li> If the argument is negative infinity, the result is 1640 * negative infinity. 1641 * 1642 * <li> If the argument is zero, the result is 1643 * {@code -Float.MIN_VALUE} 1644 * 1645 * </ul> 1646 * 1647 * @param f starting floating-point value 1648 * @return The adjacent floating-point value closer to negative 1649 * infinity. 1650 * @since 1.8 1651 */ 1652 public static float nextDown(float f) { 1653 return Math.nextDown(f); 1654 } 1655 1656 /** 1657 * Returns {@code d} × 1658 * 2<sup>{@code scaleFactor}</sup> rounded as if performed 1659 * by a single correctly rounded floating-point multiply to a 1660 * member of the double value set. See the Java 1661 * Language Specification for a discussion of floating-point 1662 * value sets. If the exponent of the result is between {@link 1663 * Double#MIN_EXPONENT} and {@link Double#MAX_EXPONENT}, the 1664 * answer is calculated exactly. If the exponent of the result 1665 * would be larger than {@code Double.MAX_EXPONENT}, an 1666 * infinity is returned. Note that if the result is subnormal, 1667 * precision may be lost; that is, when {@code scalb(x, n)} 1668 * is subnormal, {@code scalb(scalb(x, n), -n)} may not equal 1669 * <i>x</i>. When the result is non-NaN, the result has the same 1670 * sign as {@code d}. 1671 * 1672 * <p>Special cases: 1673 * <ul> 1674 * <li> If the first argument is NaN, NaN is returned. 1675 * <li> If the first argument is infinite, then an infinity of the 1676 * same sign is returned. 1677 * <li> If the first argument is zero, then a zero of the same 1678 * sign is returned. 1679 * </ul> 1680 * 1681 * @param d number to be scaled by a power of two. 1682 * @param scaleFactor power of 2 used to scale {@code d} 1683 * @return {@code d} × 2<sup>{@code scaleFactor}</sup> 1684 * @since 1.6 1685 */ 1686 public static double scalb(double d, int scaleFactor) { 1687 return Math.scalb(d, scaleFactor); 1688 } 1689 1690 /** 1691 * Returns {@code f} × 1692 * 2<sup>{@code scaleFactor}</sup> rounded as if performed 1693 * by a single correctly rounded floating-point multiply to a 1694 * member of the float value set. See the Java 1695 * Language Specification for a discussion of floating-point 1696 * value sets. If the exponent of the result is between {@link 1697 * Float#MIN_EXPONENT} and {@link Float#MAX_EXPONENT}, the 1698 * answer is calculated exactly. If the exponent of the result 1699 * would be larger than {@code Float.MAX_EXPONENT}, an 1700 * infinity is returned. Note that if the result is subnormal, 1701 * precision may be lost; that is, when {@code scalb(x, n)} 1702 * is subnormal, {@code scalb(scalb(x, n), -n)} may not equal 1703 * <i>x</i>. When the result is non-NaN, the result has the same 1704 * sign as {@code f}. 1705 * 1706 * <p>Special cases: 1707 * <ul> 1708 * <li> If the first argument is NaN, NaN is returned. 1709 * <li> If the first argument is infinite, then an infinity of the 1710 * same sign is returned. 1711 * <li> If the first argument is zero, then a zero of the same 1712 * sign is returned. 1713 * </ul> 1714 * 1715 * @param f number to be scaled by a power of two. 1716 * @param scaleFactor power of 2 used to scale {@code f} 1717 * @return {@code f} × 2<sup>{@code scaleFactor}</sup> 1718 * @since 1.6 1719 */ 1720 public static float scalb(float f, int scaleFactor) { 1721 return Math.scalb(f, scaleFactor); 1722 } 1723 }