1 /* 2 * Copyright (c) 1999, 2021, 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 28 import java.util.Random; 29 import jdk.internal.math.DoubleConsts; 30 import jdk.internal.vm.annotation.IntrinsicCandidate; 31 32 /** 33 * The class {@code StrictMath} contains methods for performing basic 34 * numeric operations such as the elementary exponential, logarithm, 35 * square root, and trigonometric functions. 36 * 37 * <p>To help ensure portability of Java programs, the definitions of 38 * some of the numeric functions in this package require that they 39 * produce the same results as certain published algorithms. These 40 * algorithms are available from the well-known network library 41 * {@code netlib} as the package "Freely Distributable Math 42 * Library," <a 43 * href="https://www.netlib.org/fdlibm/">{@code fdlibm}</a>. These 44 * algorithms, which are written in the C programming language, are 45 * then to be understood as executed with all floating-point 46 * operations following the rules of Java floating-point arithmetic. 47 * 48 * <p>The Java math library is defined with respect to 49 * {@code fdlibm} version 5.3. Where {@code fdlibm} provides 50 * more than one definition for a function (such as 51 * {@code acos}), use the "IEEE 754 core function" version 52 * (residing in a file whose name begins with the letter 53 * {@code e}). The methods which require {@code fdlibm} 54 * semantics are {@code sin}, {@code cos}, {@code tan}, 55 * {@code asin}, {@code acos}, {@code atan}, 56 * {@code exp}, {@code log}, {@code log10}, 57 * {@code cbrt}, {@code atan2}, {@code pow}, 58 * {@code sinh}, {@code cosh}, {@code tanh}, 59 * {@code hypot}, {@code expm1}, and {@code log1p}. 60 * 61 * <p> 62 * The platform uses signed two's complement integer arithmetic with 63 * int and long primitive types. The developer should choose 64 * the primitive type to ensure that arithmetic operations consistently 65 * produce correct results, which in some cases means the operations 66 * will not overflow the range of values of the computation. 67 * The best practice is to choose the primitive type and algorithm to avoid 68 * overflow. In cases where the size is {@code int} or {@code long} and 69 * overflow errors need to be detected, the methods {@code addExact}, 70 * {@code subtractExact}, {@code multiplyExact}, {@code toIntExact}, 71 * {@code incrementExact}, {@code decrementExact} and {@code negateExact} 72 * throw an {@code ArithmeticException} when the results overflow. 73 * For the arithmetic operations divide and absolute value, overflow 74 * occurs only with a specific minimum or maximum value and 75 * should be checked against the minimum or maximum as appropriate. 76 * 77 * <h2><a id=Ieee754RecommendedOps>IEEE 754 Recommended 78 * Operations</a></h2> 79 * 80 * The {@link java.lang.Math Math} class discusses how the shared 81 * quality of implementation criteria for selected {@code Math} and 82 * {@code StrictMath} methods <a 83 * href="Math.html#Ieee754RecommendedOps">relate to the IEEE 754 84 * recommended operations</a>. 85 * 86 * @author Joseph D. Darcy 87 * @since 1.3 88 */ 89 public final class StrictMath { 90 91 /** 92 * Don't let anyone instantiate this class. 93 */ StrictMath()94 private StrictMath() {} 95 96 /** 97 * The {@code double} value that is closer than any other to 98 * <i>e</i>, the base of the natural logarithms. 99 */ 100 public static final double E = 2.7182818284590452354; 101 102 /** 103 * The {@code double} value that is closer than any other to 104 * <i>pi</i>, the ratio of the circumference of a circle to its 105 * diameter. 106 */ 107 public static final double PI = 3.14159265358979323846; 108 109 /** 110 * Constant by which to multiply an angular value in degrees to obtain an 111 * angular value in radians. 112 */ 113 private static final double DEGREES_TO_RADIANS = 0.017453292519943295; 114 115 /** 116 * Constant by which to multiply an angular value in radians to obtain an 117 * angular value in degrees. 118 */ 119 120 private static final double RADIANS_TO_DEGREES = 57.29577951308232; 121 122 /** 123 * Returns the trigonometric sine of an angle. Special cases: 124 * <ul><li>If the argument is NaN or an infinity, then the 125 * result is NaN. 126 * <li>If the argument is zero, then the result is a zero with the 127 * same sign as the argument.</ul> 128 * 129 * @param a an angle, in radians. 130 * @return the sine of the argument. 131 */ sin(double a)132 public static native double sin(double a); 133 134 /** 135 * Returns the trigonometric cosine of an angle. Special cases: 136 * <ul><li>If the argument is NaN or an infinity, then the 137 * result is NaN. 138 * <li>If the argument is zero, then the result is {@code 1.0}. 139 * </ul> 140 * 141 * @param a an angle, in radians. 142 * @return the cosine of the argument. 143 */ cos(double a)144 public static native double cos(double a); 145 146 /** 147 * Returns the trigonometric tangent of an angle. Special cases: 148 * <ul><li>If the argument is NaN or an infinity, then the result 149 * is NaN. 150 * <li>If the argument is zero, then the result is a zero with the 151 * same sign as the argument.</ul> 152 * 153 * @param a an angle, in radians. 154 * @return the tangent of the argument. 155 */ tan(double a)156 public static native double tan(double a); 157 158 /** 159 * Returns the arc sine of a value; the returned angle is in the 160 * range -<i>pi</i>/2 through <i>pi</i>/2. Special cases: 161 * <ul><li>If the argument is NaN or its absolute value is greater 162 * than 1, then the result is NaN. 163 * <li>If the argument is zero, then the result is a zero with the 164 * same sign as the argument.</ul> 165 * 166 * @param a the value whose arc sine is to be returned. 167 * @return the arc sine of the argument. 168 */ asin(double a)169 public static native double asin(double a); 170 171 /** 172 * Returns the arc cosine of a value; the returned angle is in the 173 * range 0.0 through <i>pi</i>. Special case: 174 * <ul><li>If the argument is NaN or its absolute value is greater 175 * than 1, then the result is NaN. 176 * <li>If the argument is {@code 1.0}, the result is positive zero. 177 * </ul> 178 * 179 * @param a the value whose arc cosine is to be returned. 180 * @return the arc cosine of the argument. 181 */ acos(double a)182 public static native double acos(double a); 183 184 /** 185 * Returns the arc tangent of a value; the returned angle is in the 186 * range -<i>pi</i>/2 through <i>pi</i>/2. Special cases: 187 * <ul><li>If the argument is NaN, then the result is NaN. 188 * <li>If the argument is zero, then the result is a zero with the 189 * same sign as the argument. 190 * <li>If the argument is {@linkplain Double#isInfinite infinite}, 191 * then the result is the closest value to <i>pi</i>/2 with the 192 * same sign as the input. 193 * </ul> 194 * 195 * @param a the value whose arc tangent is to be returned. 196 * @return the arc tangent of the argument. 197 */ atan(double a)198 public static native double atan(double a); 199 200 /** 201 * Converts an angle measured in degrees to an approximately 202 * equivalent angle measured in radians. The conversion from 203 * degrees to radians is generally inexact. 204 * 205 * @param angdeg an angle, in degrees 206 * @return the measurement of the angle {@code angdeg} 207 * in radians. 208 */ toRadians(double angdeg)209 public static strictfp double toRadians(double angdeg) { 210 // Do not delegate to Math.toRadians(angdeg) because 211 // this method has the strictfp modifier. 212 return angdeg * DEGREES_TO_RADIANS; 213 } 214 215 /** 216 * Converts an angle measured in radians to an approximately 217 * equivalent angle measured in degrees. The conversion from 218 * radians to degrees is generally inexact; users should 219 * <i>not</i> expect {@code cos(toRadians(90.0))} to exactly 220 * equal {@code 0.0}. 221 * 222 * @param angrad an angle, in radians 223 * @return the measurement of the angle {@code angrad} 224 * in degrees. 225 */ toDegrees(double angrad)226 public static strictfp double toDegrees(double angrad) { 227 // Do not delegate to Math.toDegrees(angrad) because 228 // this method has the strictfp modifier. 229 return angrad * RADIANS_TO_DEGREES; 230 } 231 232 /** 233 * Returns Euler's number <i>e</i> raised to the power of a 234 * {@code double} value. Special cases: 235 * <ul><li>If the argument is NaN, the result is NaN. 236 * <li>If the argument is positive infinity, then the result is 237 * positive infinity. 238 * <li>If the argument is negative infinity, then the result is 239 * positive zero. 240 * <li>If the argument is zero, then the result is {@code 1.0}. 241 * </ul> 242 * 243 * @param a the exponent to raise <i>e</i> to. 244 * @return the value <i>e</i><sup>{@code a}</sup>, 245 * where <i>e</i> is the base of the natural logarithms. 246 */ 247 // BEGIN Android-changed: Reimplement in native 248 /* 249 public static double exp(double a) { 250 return FdLibm.Exp.compute(a); 251 } 252 */ 253 // END Android-changed: Reimplement in native exp(double a)254 public static native double exp(double a); 255 256 /** 257 * Returns the natural logarithm (base <i>e</i>) of a {@code double} 258 * value. Special cases: 259 * <ul><li>If the argument is NaN or less than zero, then the result 260 * is NaN. 261 * <li>If the argument is positive infinity, then the result is 262 * positive infinity. 263 * <li>If the argument is positive zero or negative zero, then the 264 * result is negative infinity. 265 * <li>If the argument is {@code 1.0}, then the result is positive 266 * zero. 267 * </ul> 268 * 269 * @param a a value 270 * @return the value ln {@code a}, the natural logarithm of 271 * {@code a}. 272 */ log(double a)273 public static native double log(double a); 274 275 /** 276 * Returns the base 10 logarithm of a {@code double} value. 277 * Special cases: 278 * 279 * <ul><li>If the argument is NaN or less than zero, then the result 280 * is NaN. 281 * <li>If the argument is positive infinity, then the result is 282 * positive infinity. 283 * <li>If the argument is positive zero or negative zero, then the 284 * result is negative infinity. 285 * <li>If the argument is equal to 10<sup><i>n</i></sup> for 286 * integer <i>n</i>, then the result is <i>n</i>. In particular, 287 * if the argument is {@code 1.0} (10<sup>0</sup>), then the 288 * result is positive zero. 289 * </ul> 290 * 291 * @param a a value 292 * @return the base 10 logarithm of {@code a}. 293 * @since 1.5 294 */ log10(double a)295 public static native double log10(double a); 296 297 /** 298 * Returns the correctly rounded positive square root of a 299 * {@code double} value. 300 * Special cases: 301 * <ul><li>If the argument is NaN or less than zero, then the result 302 * is NaN. 303 * <li>If the argument is positive infinity, then the result is positive 304 * infinity. 305 * <li>If the argument is positive zero or negative zero, then the 306 * result is the same as the argument.</ul> 307 * Otherwise, the result is the {@code double} value closest to 308 * the true mathematical square root of the argument value. 309 * 310 * @param a a value. 311 * @return the positive square root of {@code a}. 312 */ 313 @IntrinsicCandidate sqrt(double a)314 public static native double sqrt(double a); 315 316 /** 317 * Returns the cube root of a {@code double} value. For 318 * positive finite {@code x}, {@code cbrt(-x) == 319 * -cbrt(x)}; that is, the cube root of a negative value is 320 * the negative of the cube root of that value's magnitude. 321 * Special cases: 322 * 323 * <ul> 324 * 325 * <li>If the argument is NaN, then the result is NaN. 326 * 327 * <li>If the argument is infinite, then the result is an infinity 328 * with the same sign as the argument. 329 * 330 * <li>If the argument is zero, then the result is a zero with the 331 * same sign as the argument. 332 * 333 * </ul> 334 * 335 * @param a a value. 336 * @return the cube root of {@code a}. 337 * @since 1.5 338 */ 339 // BEGIN Android-changed: Reimplement in native 340 /* 341 public static double cbrt(double a) { 342 return FdLibm.Cbrt.compute(a); 343 } 344 */ 345 // END Android-changed: Reimplement in native cbrt(double a)346 public static native double cbrt(double a); 347 348 /** 349 * Computes the remainder operation on two arguments as prescribed 350 * by the IEEE 754 standard. 351 * The remainder value is mathematically equal to 352 * <code>f1 - f2</code> × <i>n</i>, 353 * where <i>n</i> is the mathematical integer closest to the exact 354 * mathematical value of the quotient {@code f1/f2}, and if two 355 * mathematical integers are equally close to {@code f1/f2}, 356 * then <i>n</i> is the integer that is even. If the remainder is 357 * zero, its sign is the same as the sign of the first argument. 358 * Special cases: 359 * <ul><li>If either argument is NaN, or the first argument is infinite, 360 * or the second argument is positive zero or negative zero, then the 361 * result is NaN. 362 * <li>If the first argument is finite and the second argument is 363 * infinite, then the result is the same as the first argument.</ul> 364 * 365 * @param f1 the dividend. 366 * @param f2 the divisor. 367 * @return the remainder when {@code f1} is divided by 368 * {@code f2}. 369 */ IEEEremainder(double f1, double f2)370 public static native double IEEEremainder(double f1, double f2); 371 372 /** 373 * Returns the smallest (closest to negative infinity) 374 * {@code double} value that is greater than or equal to the 375 * argument and is equal to a mathematical integer. Special cases: 376 * <ul><li>If the argument value is already equal to a 377 * mathematical integer, then the result is the same as the 378 * argument. <li>If the argument is NaN or an infinity or 379 * positive zero or negative zero, then the result is the same as 380 * the argument. <li>If the argument value is less than zero but 381 * greater than -1.0, then the result is negative zero.</ul> Note 382 * that the value of {@code StrictMath.ceil(x)} is exactly the 383 * value of {@code -StrictMath.floor(-x)}. 384 * 385 * @param a a value. 386 * @return the smallest (closest to negative infinity) 387 * floating-point value that is greater than or equal to 388 * the argument and is equal to a mathematical integer. 389 */ ceil(double a)390 public static double ceil(double a) { 391 return floorOrCeil(a, -0.0, 1.0, 1.0); 392 } 393 394 /** 395 * Returns the largest (closest to positive infinity) 396 * {@code double} value that is less than or equal to the 397 * argument and is equal to a mathematical integer. Special cases: 398 * <ul><li>If the argument value is already equal to a 399 * mathematical integer, then the result is the same as the 400 * argument. <li>If the argument is NaN or an infinity or 401 * positive zero or negative zero, then the result is the same as 402 * the argument.</ul> 403 * 404 * @param a a value. 405 * @return the largest (closest to positive infinity) 406 * floating-point value that less than or equal to the argument 407 * and is equal to a mathematical integer. 408 */ floor(double a)409 public static double floor(double a) { 410 return floorOrCeil(a, -1.0, 0.0, -1.0); 411 } 412 413 /** 414 * Internal method to share logic between floor and ceil. 415 * 416 * @param a the value to be floored or ceiled 417 * @param negativeBoundary result for values in (-1, 0) 418 * @param positiveBoundary result for values in (0, 1) 419 * @param increment value to add when the argument is non-integral 420 */ floorOrCeil(double a, double negativeBoundary, double positiveBoundary, double sign)421 private static double floorOrCeil(double a, 422 double negativeBoundary, 423 double positiveBoundary, 424 double sign) { 425 int exponent = Math.getExponent(a); 426 427 if (exponent < 0) { 428 /* 429 * Absolute value of argument is less than 1. 430 * floorOrceil(-0.0) => -0.0 431 * floorOrceil(+0.0) => +0.0 432 */ 433 return ((a == 0.0) ? a : 434 ( (a < 0.0) ? negativeBoundary : positiveBoundary) ); 435 } else if (exponent >= 52) { 436 /* 437 * Infinity, NaN, or a value so large it must be integral. 438 */ 439 return a; 440 } 441 // Else the argument is either an integral value already XOR it 442 // has to be rounded to one. 443 assert exponent >= 0 && exponent <= 51; 444 445 long doppel = Double.doubleToRawLongBits(a); 446 long mask = DoubleConsts.SIGNIF_BIT_MASK >> exponent; 447 448 if ( (mask & doppel) == 0L ) 449 return a; // integral value 450 else { 451 double result = Double.longBitsToDouble(doppel & (~mask)); 452 if (sign*a > 0.0) 453 result = result + sign; 454 return result; 455 } 456 } 457 458 /** 459 * Returns the {@code double} value that is closest in value 460 * to the argument and is equal to a mathematical integer. If two 461 * {@code double} values that are mathematical integers are 462 * equally close to the value of the argument, the result is the 463 * integer value that is even. Special cases: 464 * <ul><li>If the argument value is already equal to a mathematical 465 * integer, then the result is the same as the argument. 466 * <li>If the argument is NaN or an infinity or positive zero or negative 467 * zero, then the result is the same as the argument.</ul> 468 * 469 * @param a a value. 470 * @return the closest floating-point value to {@code a} that is 471 * equal to a mathematical integer. 472 * @author Joseph D. Darcy 473 */ rint(double a)474 public static double rint(double a) { 475 /* 476 * If the absolute value of a is not less than 2^52, it 477 * is either a finite integer (the double format does not have 478 * enough significand bits for a number that large to have any 479 * fractional portion), an infinity, or a NaN. In any of 480 * these cases, rint of the argument is the argument. 481 * 482 * Otherwise, the sum (twoToThe52 + a ) will properly round 483 * away any fractional portion of a since ulp(twoToThe52) == 484 * 1.0; subtracting out twoToThe52 from this sum will then be 485 * exact and leave the rounded integer portion of a. 486 */ 487 double twoToThe52 = (double)(1L << 52); // 2^52 488 double sign = Math.copySign(1.0, a); // preserve sign info 489 a = Math.abs(a); 490 491 if (a < twoToThe52) { // E_min <= ilogb(a) <= 51 492 a = ((twoToThe52 + a ) - twoToThe52); 493 } 494 495 return sign * a; // restore original sign 496 } 497 498 /** 499 * Returns the angle <i>theta</i> from the conversion of rectangular 500 * coordinates ({@code x}, {@code y}) to polar 501 * coordinates (r, <i>theta</i>). 502 * This method computes the phase <i>theta</i> by computing an arc tangent 503 * of {@code y/x} in the range of -<i>pi</i> to <i>pi</i>. Special 504 * cases: 505 * <ul><li>If either argument is NaN, then the result is NaN. 506 * <li>If the first argument is positive zero and the second argument 507 * is positive, or the first argument is positive and finite and the 508 * second argument is positive infinity, then the result is positive 509 * zero. 510 * <li>If the first argument is negative zero and the second argument 511 * is positive, or the first argument is negative and finite and the 512 * second argument is positive infinity, then the result is negative zero. 513 * <li>If the first argument is positive zero and the second argument 514 * is negative, or the first argument is positive and finite and the 515 * second argument is negative infinity, then the result is the 516 * {@code double} value closest to <i>pi</i>. 517 * <li>If the first argument is negative zero and the second argument 518 * is negative, or the first argument is negative and finite and the 519 * second argument is negative infinity, then the result is the 520 * {@code double} value closest to -<i>pi</i>. 521 * <li>If the first argument is positive and the second argument is 522 * positive zero or negative zero, or the first argument is positive 523 * infinity and the second argument is finite, then the result is the 524 * {@code double} value closest to <i>pi</i>/2. 525 * <li>If the first argument is negative and the second argument is 526 * positive zero or negative zero, or the first argument is negative 527 * infinity and the second argument is finite, then the result is the 528 * {@code double} value closest to -<i>pi</i>/2. 529 * <li>If both arguments are positive infinity, then the result is the 530 * {@code double} value closest to <i>pi</i>/4. 531 * <li>If the first argument is positive infinity and the second argument 532 * is negative infinity, then the result is the {@code double} 533 * value closest to 3*<i>pi</i>/4. 534 * <li>If the first argument is negative infinity and the second argument 535 * is positive infinity, then the result is the {@code double} value 536 * closest to -<i>pi</i>/4. 537 * <li>If both arguments are negative infinity, then the result is the 538 * {@code double} value closest to -3*<i>pi</i>/4.</ul> 539 * 540 * @apiNote 541 * For <i>y</i> with a positive sign and finite nonzero 542 * <i>x</i>, the exact mathematical value of {@code atan2} is 543 * equal to: 544 * <ul> 545 * <li>If <i>x</i> {@literal >} 0, atan(abs(<i>y</i>/<i>x</i>)) 546 * <li>If <i>x</i> {@literal <} 0, π - atan(abs(<i>y</i>/<i>x</i>)) 547 * </ul> 548 * 549 * @param y the ordinate coordinate 550 * @param x the abscissa coordinate 551 * @return the <i>theta</i> component of the point 552 * (<i>r</i>, <i>theta</i>) 553 * in polar coordinates that corresponds to the point 554 * (<i>x</i>, <i>y</i>) in Cartesian coordinates. 555 */ atan2(double y, double x)556 public static native double atan2(double y, double x); 557 558 /** 559 * Returns the value of the first argument raised to the power of the 560 * second argument. Special cases: 561 * 562 * <ul><li>If the second argument is positive or negative zero, then the 563 * result is 1.0. 564 * <li>If the second argument is 1.0, then the result is the same as the 565 * first argument. 566 * <li>If the second argument is NaN, then the result is NaN. 567 * <li>If the first argument is NaN and the second argument is nonzero, 568 * then the result is NaN. 569 * 570 * <li>If 571 * <ul> 572 * <li>the absolute value of the first argument is greater than 1 573 * and the second argument is positive infinity, or 574 * <li>the absolute value of the first argument is less than 1 and 575 * the second argument is negative infinity, 576 * </ul> 577 * then the result is positive infinity. 578 * 579 * <li>If 580 * <ul> 581 * <li>the absolute value of the first argument is greater than 1 and 582 * the second argument is negative infinity, or 583 * <li>the absolute value of the 584 * first argument is less than 1 and the second argument is positive 585 * infinity, 586 * </ul> 587 * then the result is positive zero. 588 * 589 * <li>If the absolute value of the first argument equals 1 and the 590 * second argument is infinite, then the result is NaN. 591 * 592 * <li>If 593 * <ul> 594 * <li>the first argument is positive zero and the second argument 595 * is greater than zero, or 596 * <li>the first argument is positive infinity and the second 597 * argument is less than zero, 598 * </ul> 599 * then the result is positive zero. 600 * 601 * <li>If 602 * <ul> 603 * <li>the first argument is positive zero and the second argument 604 * is less than zero, or 605 * <li>the first argument is positive infinity and the second 606 * argument is greater than zero, 607 * </ul> 608 * then the result is positive infinity. 609 * 610 * <li>If 611 * <ul> 612 * <li>the first argument is negative zero and the second argument 613 * is greater than zero but not a finite odd integer, or 614 * <li>the first argument is negative infinity and the second 615 * argument is less than zero but not a finite odd integer, 616 * </ul> 617 * then the result is positive zero. 618 * 619 * <li>If 620 * <ul> 621 * <li>the first argument is negative zero and the second argument 622 * is a positive finite odd integer, or 623 * <li>the first argument is negative infinity and the second 624 * argument is a negative finite odd integer, 625 * </ul> 626 * then the result is negative zero. 627 * 628 * <li>If 629 * <ul> 630 * <li>the first argument is negative zero and the second argument 631 * is less than zero but not a finite odd integer, or 632 * <li>the first argument is negative infinity and the second 633 * argument is greater than zero but not a finite odd integer, 634 * </ul> 635 * then the result is positive infinity. 636 * 637 * <li>If 638 * <ul> 639 * <li>the first argument is negative zero and the second argument 640 * is a negative finite odd integer, or 641 * <li>the first argument is negative infinity and the second 642 * argument is a positive finite odd integer, 643 * </ul> 644 * then the result is negative infinity. 645 * 646 * <li>If the first argument is finite and less than zero 647 * <ul> 648 * <li> if the second argument is a finite even integer, the 649 * result is equal to the result of raising the absolute value of 650 * the first argument to the power of the second argument 651 * 652 * <li>if the second argument is a finite odd integer, the result 653 * is equal to the negative of the result of raising the absolute 654 * value of the first argument to the power of the second 655 * argument 656 * 657 * <li>if the second argument is finite and not an integer, then 658 * the result is NaN. 659 * </ul> 660 * 661 * <li>If both arguments are integers, then the result is exactly equal 662 * to the mathematical result of raising the first argument to the power 663 * of the second argument if that result can in fact be represented 664 * exactly as a {@code double} value.</ul> 665 * 666 * <p>(In the foregoing descriptions, a floating-point value is 667 * considered to be an integer if and only if it is finite and a 668 * fixed point of the method {@link #ceil ceil} or, 669 * equivalently, a fixed point of the method {@link #floor 670 * floor}. A value is a fixed point of a one-argument 671 * method if and only if the result of applying the method to the 672 * value is equal to the value.) 673 * 674 * @apiNote 675 * The special cases definitions of this method differ from the 676 * special case definitions of the IEEE 754 recommended {@code 677 * pow} operation for ±{@code 1.0} raised to an infinite 678 * power. This method treats such cases as indeterminate and 679 * specifies a NaN is returned. The IEEE 754 specification treats 680 * the infinite power as a large integer (large-magnitude 681 * floating-point numbers are numerically integers, specifically 682 * even integers) and therefore specifies {@code 1.0} be returned. 683 * 684 * @param a base. 685 * @param b the exponent. 686 * @return the value {@code a}<sup>{@code b}</sup>. 687 */ 688 // BEGIN Android-changed: Reimplement in native 689 /* 690 public static double pow(double a, double b) { 691 return FdLibm.Pow.compute(a, b); 692 } 693 */ 694 // END Android-changed: Reimplement in native pow(double a, double b)695 public static native double pow(double a, double b); 696 697 /** 698 * Returns the closest {@code int} to the argument, with ties 699 * rounding to positive infinity. 700 * 701 * <p>Special cases: 702 * <ul><li>If the argument is NaN, the result is 0. 703 * <li>If the argument is negative infinity or any value less than or 704 * equal to the value of {@code Integer.MIN_VALUE}, the result is 705 * equal to the value of {@code Integer.MIN_VALUE}. 706 * <li>If the argument is positive infinity or any value greater than or 707 * equal to the value of {@code Integer.MAX_VALUE}, the result is 708 * equal to the value of {@code Integer.MAX_VALUE}.</ul> 709 * 710 * @param a a floating-point value to be rounded to an integer. 711 * @return the value of the argument rounded to the nearest 712 * {@code int} value. 713 * @see java.lang.Integer#MAX_VALUE 714 * @see java.lang.Integer#MIN_VALUE 715 */ round(float a)716 public static int round(float a) { 717 return Math.round(a); 718 } 719 720 /** 721 * Returns the closest {@code long} to the argument, with ties 722 * rounding to positive infinity. 723 * 724 * <p>Special cases: 725 * <ul><li>If the argument is NaN, the result is 0. 726 * <li>If the argument is negative infinity or any value less than or 727 * equal to the value of {@code Long.MIN_VALUE}, the result is 728 * equal to the value of {@code Long.MIN_VALUE}. 729 * <li>If the argument is positive infinity or any value greater than or 730 * equal to the value of {@code Long.MAX_VALUE}, the result is 731 * equal to the value of {@code Long.MAX_VALUE}.</ul> 732 * 733 * @param a a floating-point value to be rounded to a 734 * {@code long}. 735 * @return the value of the argument rounded to the nearest 736 * {@code long} value. 737 * @see java.lang.Long#MAX_VALUE 738 * @see java.lang.Long#MIN_VALUE 739 */ round(double a)740 public static long round(double a) { 741 return Math.round(a); 742 } 743 744 private static final class RandomNumberGeneratorHolder { 745 static final Random randomNumberGenerator = new Random(); 746 } 747 748 /** 749 * Returns a {@code double} value with a positive sign, greater 750 * than or equal to {@code 0.0} and less than {@code 1.0}. 751 * Returned values are chosen pseudorandomly with (approximately) 752 * uniform distribution from that range. 753 * 754 * <p>When this method is first called, it creates a single new 755 * pseudorandom-number generator, exactly as if by the expression 756 * 757 * <blockquote>{@code new java.util.Random()}</blockquote> 758 * 759 * This new pseudorandom-number generator is used thereafter for 760 * all calls to this method and is used nowhere else. 761 * 762 * <p>This method is properly synchronized to allow correct use by 763 * more than one thread. However, if many threads need to generate 764 * pseudorandom numbers at a great rate, it may reduce contention 765 * for each thread to have its own pseudorandom-number generator. 766 * 767 * @return a pseudorandom {@code double} greater than or equal 768 * to {@code 0.0} and less than {@code 1.0}. 769 * @see Random#nextDouble() 770 */ random()771 public static double random() { 772 return RandomNumberGeneratorHolder.randomNumberGenerator.nextDouble(); 773 } 774 775 /** 776 * Returns the sum of its arguments, 777 * throwing an exception if the result overflows an {@code int}. 778 * 779 * @param x the first value 780 * @param y the second value 781 * @return the result 782 * @throws ArithmeticException if the result overflows an int 783 * @see Math#addExact(int,int) 784 * @since 1.8 785 */ addExact(int x, int y)786 public static int addExact(int x, int y) { 787 return Math.addExact(x, y); 788 } 789 790 /** 791 * Returns the sum of its arguments, 792 * throwing an exception if the result overflows a {@code long}. 793 * 794 * @param x the first value 795 * @param y the second value 796 * @return the result 797 * @throws ArithmeticException if the result overflows a long 798 * @see Math#addExact(long,long) 799 * @since 1.8 800 */ addExact(long x, long y)801 public static long addExact(long x, long y) { 802 return Math.addExact(x, y); 803 } 804 805 /** 806 * Returns the difference of the arguments, 807 * throwing an exception if the result overflows an {@code int}. 808 * 809 * @param x the first value 810 * @param y the second value to subtract from the first 811 * @return the result 812 * @throws ArithmeticException if the result overflows an int 813 * @see Math#subtractExact(int,int) 814 * @since 1.8 815 */ subtractExact(int x, int y)816 public static int subtractExact(int x, int y) { 817 return Math.subtractExact(x, y); 818 } 819 820 /** 821 * Returns the difference of the arguments, 822 * throwing an exception if the result overflows a {@code long}. 823 * 824 * @param x the first value 825 * @param y the second value to subtract from the first 826 * @return the result 827 * @throws ArithmeticException if the result overflows a long 828 * @see Math#subtractExact(long,long) 829 * @since 1.8 830 */ subtractExact(long x, long y)831 public static long subtractExact(long x, long y) { 832 return Math.subtractExact(x, y); 833 } 834 835 /** 836 * Returns the product of the arguments, 837 * throwing an exception if the result overflows an {@code int}. 838 * 839 * @param x the first value 840 * @param y the second value 841 * @return the result 842 * @throws ArithmeticException if the result overflows an int 843 * @see Math#multiplyExact(int,int) 844 * @since 1.8 845 */ multiplyExact(int x, int y)846 public static int multiplyExact(int x, int y) { 847 return Math.multiplyExact(x, y); 848 } 849 850 /** 851 * Returns the product of the arguments, throwing an exception if the result 852 * overflows a {@code long}. 853 * 854 * @param x the first value 855 * @param y the second value 856 * @return the result 857 * @throws ArithmeticException if the result overflows a long 858 * @see Math#multiplyExact(long,int) 859 * @since 9 860 */ multiplyExact(long x, int y)861 public static long multiplyExact(long x, int y) { 862 return Math.multiplyExact(x, y); 863 } 864 865 /** 866 * Returns the product of the arguments, 867 * throwing an exception if the result overflows a {@code long}. 868 * 869 * @param x the first value 870 * @param y the second value 871 * @return the result 872 * @throws ArithmeticException if the result overflows a long 873 * @see Math#multiplyExact(long,long) 874 * @since 1.8 875 */ multiplyExact(long x, long y)876 public static long multiplyExact(long x, long y) { 877 return Math.multiplyExact(x, y); 878 } 879 880 /** 881 * Returns the argument incremented by one, 882 * throwing an exception if the result overflows an {@code int}. 883 * The overflow only occurs for {@linkplain Integer#MAX_VALUE the maximum value}. 884 * 885 * @param a the value to increment 886 * @return the result 887 * @throws ArithmeticException if the result overflows an int 888 * @see Math#incrementExact(int) 889 * @since 14 890 */ incrementExact(int a)891 public static int incrementExact(int a) { 892 return Math.incrementExact(a); 893 } 894 895 /** 896 * Returns the argument incremented by one, 897 * throwing an exception if the result overflows a {@code long}. 898 * The overflow only occurs for {@linkplain Long#MAX_VALUE the maximum value}. 899 * 900 * @param a the value to increment 901 * @return the result 902 * @throws ArithmeticException if the result overflows a long 903 * @see Math#incrementExact(long) 904 * @since 14 905 */ incrementExact(long a)906 public static long incrementExact(long a) { 907 return Math.incrementExact(a); 908 } 909 910 /** 911 * Returns the argument decremented by one, 912 * throwing an exception if the result overflows an {@code int}. 913 * The overflow only occurs for {@linkplain Integer#MIN_VALUE the minimum value}. 914 * 915 * @param a the value to decrement 916 * @return the result 917 * @throws ArithmeticException if the result overflows an int 918 * @see Math#decrementExact(int) 919 * @since 14 920 */ decrementExact(int a)921 public static int decrementExact(int a) { 922 return Math.decrementExact(a); 923 } 924 925 /** 926 * Returns the argument decremented by one, 927 * throwing an exception if the result overflows a {@code long}. 928 * The overflow only occurs for {@linkplain Long#MIN_VALUE the minimum value}. 929 * 930 * @param a the value to decrement 931 * @return the result 932 * @throws ArithmeticException if the result overflows a long 933 * @see Math#decrementExact(long) 934 * @since 14 935 */ decrementExact(long a)936 public static long decrementExact(long a) { 937 return Math.decrementExact(a); 938 } 939 940 /** 941 * Returns the negation of the argument, 942 * throwing an exception if the result overflows an {@code int}. 943 * The overflow only occurs for {@linkplain Integer#MIN_VALUE the minimum value}. 944 * 945 * @param a the value to negate 946 * @return the result 947 * @throws ArithmeticException if the result overflows an int 948 * @see Math#negateExact(int) 949 * @since 14 950 */ negateExact(int a)951 public static int negateExact(int a) { 952 return Math.negateExact(a); 953 } 954 955 /** 956 * Returns the negation of the argument, 957 * throwing an exception if the result overflows a {@code long}. 958 * The overflow only occurs for {@linkplain Long#MIN_VALUE the minimum value}. 959 * 960 * @param a the value to negate 961 * @return the result 962 * @throws ArithmeticException if the result overflows a long 963 * @see Math#negateExact(long) 964 * @since 14 965 */ negateExact(long a)966 public static long negateExact(long a) { 967 return Math.negateExact(a); 968 } 969 970 /** 971 * Returns the value of the {@code long} argument, throwing an exception 972 * if the value overflows an {@code int}. 973 * 974 * @param value the long value 975 * @return the argument as an int 976 * @throws ArithmeticException if the {@code argument} overflows an int 977 * @see Math#toIntExact(long) 978 * @since 1.8 979 */ toIntExact(long value)980 public static int toIntExact(long value) { 981 return Math.toIntExact(value); 982 } 983 984 /** 985 * Returns the exact mathematical product of the arguments. 986 * 987 * @param x the first value 988 * @param y the second value 989 * @return the result 990 * @see Math#multiplyFull(int,int) 991 * @since 9 992 */ multiplyFull(int x, int y)993 public static long multiplyFull(int x, int y) { 994 return Math.multiplyFull(x, y); 995 } 996 997 /** 998 * Returns as a {@code long} the most significant 64 bits of the 128-bit 999 * product of two 64-bit factors. 1000 * 1001 * @param x the first value 1002 * @param y the second value 1003 * @return the result 1004 * @see Math#multiplyHigh(long,long) 1005 * @since 9 1006 */ multiplyHigh(long x, long y)1007 public static long multiplyHigh(long x, long y) { 1008 return Math.multiplyHigh(x, y); 1009 } 1010 1011 /** 1012 * Returns the largest (closest to positive infinity) 1013 * {@code int} value that is less than or equal to the algebraic quotient. 1014 * There is one special case, if the dividend is the 1015 * {@linkplain Integer#MIN_VALUE Integer.MIN_VALUE} and the divisor is {@code -1}, 1016 * then integer overflow occurs and 1017 * the result is equal to the {@code Integer.MIN_VALUE}. 1018 * <p> 1019 * See {@link Math#floorDiv(int, int) Math.floorDiv} for examples and 1020 * a comparison to the integer division {@code /} operator. 1021 * 1022 * @param x the dividend 1023 * @param y the divisor 1024 * @return the largest (closest to positive infinity) 1025 * {@code int} value that is less than or equal to the algebraic quotient. 1026 * @throws ArithmeticException if the divisor {@code y} is zero 1027 * @see Math#floorDiv(int, int) 1028 * @see Math#floor(double) 1029 * @since 1.8 1030 */ floorDiv(int x, int y)1031 public static int floorDiv(int x, int y) { 1032 return Math.floorDiv(x, y); 1033 } 1034 1035 /** 1036 * Returns the largest (closest to positive infinity) 1037 * {@code long} value that is less than or equal to the algebraic quotient. 1038 * There is one special case, if the dividend is the 1039 * {@linkplain Long#MIN_VALUE Long.MIN_VALUE} and the divisor is {@code -1}, 1040 * then integer overflow occurs and 1041 * the result is equal to {@code Long.MIN_VALUE}. 1042 * <p> 1043 * See {@link Math#floorDiv(int, int) Math.floorDiv} for examples and 1044 * a comparison to the integer division {@code /} operator. 1045 * 1046 * @param x the dividend 1047 * @param y the divisor 1048 * @return the largest (closest to positive infinity) 1049 * {@code int} value that is less than or equal to the algebraic quotient. 1050 * @throws ArithmeticException if the divisor {@code y} is zero 1051 * @see Math#floorDiv(long, int) 1052 * @see Math#floor(double) 1053 * @since 9 1054 */ floorDiv(long x, int y)1055 public static long floorDiv(long x, int y) { 1056 return Math.floorDiv(x, y); 1057 } 1058 1059 /** 1060 * Returns the largest (closest to positive infinity) 1061 * {@code long} value that is less than or equal to the algebraic quotient. 1062 * There is one special case, if the dividend is the 1063 * {@linkplain Long#MIN_VALUE Long.MIN_VALUE} and the divisor is {@code -1}, 1064 * then integer overflow occurs and 1065 * the result is equal to the {@code Long.MIN_VALUE}. 1066 * <p> 1067 * See {@link Math#floorDiv(int, int) Math.floorDiv} for examples and 1068 * a comparison to the integer division {@code /} operator. 1069 * 1070 * @param x the dividend 1071 * @param y the divisor 1072 * @return the largest (closest to positive infinity) 1073 * {@code long} value that is less than or equal to the algebraic quotient. 1074 * @throws ArithmeticException if the divisor {@code y} is zero 1075 * @see Math#floorDiv(long, long) 1076 * @see Math#floor(double) 1077 * @since 1.8 1078 */ floorDiv(long x, long y)1079 public static long floorDiv(long x, long y) { 1080 return Math.floorDiv(x, y); 1081 } 1082 1083 /** 1084 * Returns the floor modulus of the {@code int} arguments. 1085 * <p> 1086 * The floor modulus is {@code x - (floorDiv(x, y) * y)}, 1087 * has the same sign as the divisor {@code y}, and 1088 * is in the range of {@code -abs(y) < r < +abs(y)}. 1089 * <p> 1090 * The relationship between {@code floorDiv} and {@code floorMod} is such that: 1091 * <ul> 1092 * <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x} 1093 * </ul> 1094 * <p> 1095 * See {@link Math#floorMod(int, int) Math.floorMod} for examples and 1096 * a comparison to the {@code %} operator. 1097 * 1098 * @param x the dividend 1099 * @param y the divisor 1100 * @return the floor modulus {@code x - (floorDiv(x, y) * y)} 1101 * @throws ArithmeticException if the divisor {@code y} is zero 1102 * @see Math#floorMod(int, int) 1103 * @see StrictMath#floorDiv(int, int) 1104 * @since 1.8 1105 */ floorMod(int x, int y)1106 public static int floorMod(int x, int y) { 1107 return Math.floorMod(x , y); 1108 } 1109 1110 /** 1111 * Returns the floor modulus of the {@code long} and {@code int} arguments. 1112 * <p> 1113 * The floor modulus is {@code x - (floorDiv(x, y) * y)}, 1114 * has the same sign as the divisor {@code y}, and 1115 * is in the range of {@code -abs(y) < r < +abs(y)}. 1116 * 1117 * <p> 1118 * The relationship between {@code floorDiv} and {@code floorMod} is such that: 1119 * <ul> 1120 * <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x} 1121 * </ul> 1122 * <p> 1123 * See {@link Math#floorMod(int, int) Math.floorMod} for examples and 1124 * a comparison to the {@code %} operator. 1125 * 1126 * @param x the dividend 1127 * @param y the divisor 1128 * @return the floor modulus {@code x - (floorDiv(x, y) * y)} 1129 * @throws ArithmeticException if the divisor {@code y} is zero 1130 * @see Math#floorMod(long, int) 1131 * @see StrictMath#floorDiv(long, int) 1132 * @since 9 1133 */ floorMod(long x, int y)1134 public static int floorMod(long x, int y) { 1135 return Math.floorMod(x , y); 1136 } 1137 1138 /** 1139 * Returns the floor modulus of the {@code long} arguments. 1140 * <p> 1141 * The floor modulus is {@code x - (floorDiv(x, y) * y)}, 1142 * has the same sign as the divisor {@code y}, and 1143 * is in the range of {@code -abs(y) < r < +abs(y)}. 1144 * <p> 1145 * The relationship between {@code floorDiv} and {@code floorMod} is such that: 1146 * <ul> 1147 * <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x} 1148 * </ul> 1149 * <p> 1150 * See {@link Math#floorMod(int, int) Math.floorMod} for examples and 1151 * a comparison to the {@code %} operator. 1152 * 1153 * @param x the dividend 1154 * @param y the divisor 1155 * @return the floor modulus {@code x - (floorDiv(x, y) * y)} 1156 * @throws ArithmeticException if the divisor {@code y} is zero 1157 * @see Math#floorMod(long, long) 1158 * @see StrictMath#floorDiv(long, long) 1159 * @since 1.8 1160 */ floorMod(long x, long y)1161 public static long floorMod(long x, long y) { 1162 return Math.floorMod(x, y); 1163 } 1164 1165 /** 1166 * Returns the absolute value of an {@code int} value. 1167 * If the argument is not negative, the argument is returned. 1168 * If the argument is negative, the negation of the argument is returned. 1169 * 1170 * <p>Note that if the argument is equal to the value of {@link 1171 * Integer#MIN_VALUE}, the most negative representable {@code int} 1172 * value, the result is that same value, which is negative. In 1173 * contrast, the {@link StrictMath#absExact(int)} method throws an 1174 * {@code ArithmeticException} for this value. 1175 * 1176 * @param a the argument whose absolute value is to be determined. 1177 * @return the absolute value of the argument. 1178 * @see Math#absExact(int) 1179 */ abs(int a)1180 public static int abs(int a) { 1181 return Math.abs(a); 1182 } 1183 1184 /** 1185 * Returns the mathematical absolute value of an {@code int} value 1186 * if it is exactly representable as an {@code int}, throwing 1187 * {@code ArithmeticException} if the result overflows the 1188 * positive {@code int} range. 1189 * 1190 * <p>Since the range of two's complement integers is asymmetric 1191 * with one additional negative value (JLS {@jls 4.2.1}), the 1192 * mathematical absolute value of {@link Integer#MIN_VALUE} 1193 * overflows the positive {@code int} range, so an exception is 1194 * thrown for that argument. 1195 * 1196 * @param a the argument whose absolute value is to be determined 1197 * @return the absolute value of the argument, unless overflow occurs 1198 * @throws ArithmeticException if the argument is {@link Integer#MIN_VALUE} 1199 * @see Math#abs(int) 1200 * @see Math#absExact(int) 1201 * @since 15 1202 */ absExact(int a)1203 public static int absExact(int a) { 1204 return Math.absExact(a); 1205 } 1206 1207 /** 1208 * Returns the absolute value of a {@code long} value. 1209 * If the argument is not negative, the argument is returned. 1210 * If the argument is negative, the negation of the argument is returned. 1211 * 1212 * <p>Note that if the argument is equal to the value of {@link 1213 * Long#MIN_VALUE}, the most negative representable {@code long} 1214 * value, the result is that same value, which is negative. In 1215 * contrast, the {@link StrictMath#absExact(long)} method throws 1216 * an {@code ArithmeticException} for this value. 1217 * 1218 * @param a the argument whose absolute value is to be determined. 1219 * @return the absolute value of the argument. 1220 * @see Math#absExact(long) 1221 */ abs(long a)1222 public static long abs(long a) { 1223 return Math.abs(a); 1224 } 1225 1226 /** 1227 * Returns the mathematical absolute value of an {@code long} value 1228 * if it is exactly representable as an {@code long}, throwing 1229 * {@code ArithmeticException} if the result overflows the 1230 * positive {@code long} range. 1231 * 1232 * <p>Since the range of two's complement integers is asymmetric 1233 * with one additional negative value (JLS {@jls 4.2.1}), the 1234 * mathematical absolute value of {@link Long#MIN_VALUE} overflows 1235 * the positive {@code long} range, so an exception is thrown for 1236 * that argument. 1237 * 1238 * @param a the argument whose absolute value is to be determined 1239 * @return the absolute value of the argument, unless overflow occurs 1240 * @throws ArithmeticException if the argument is {@link Long#MIN_VALUE} 1241 * @see Math#abs(long) 1242 * @see Math#absExact(long) 1243 * @since 15 1244 */ absExact(long a)1245 public static long absExact(long a) { 1246 return Math.absExact(a); 1247 } 1248 1249 /** 1250 * Returns the absolute value of a {@code float} value. 1251 * If the argument is not negative, the argument is returned. 1252 * If the argument is negative, the negation of the argument is returned. 1253 * Special cases: 1254 * <ul><li>If the argument is positive zero or negative zero, the 1255 * result is positive zero. 1256 * <li>If the argument is infinite, the result is positive infinity. 1257 * <li>If the argument is NaN, the result is NaN.</ul> 1258 * 1259 * @apiNote As implied by the above, one valid implementation of 1260 * this method is given by the expression below which computes a 1261 * {@code float} with the same exponent and significand as the 1262 * argument but with a guaranteed zero sign bit indicating a 1263 * positive value: <br> 1264 * {@code Float.intBitsToFloat(0x7fffffff & Float.floatToRawIntBits(a))} 1265 * 1266 * @param a the argument whose absolute value is to be determined 1267 * @return the absolute value of the argument. 1268 */ abs(float a)1269 public static float abs(float a) { 1270 return Math.abs(a); 1271 } 1272 1273 /** 1274 * Returns the absolute value of a {@code double} value. 1275 * If the argument is not negative, the argument is returned. 1276 * If the argument is negative, the negation of the argument is returned. 1277 * Special cases: 1278 * <ul><li>If the argument is positive zero or negative zero, the result 1279 * is positive zero. 1280 * <li>If the argument is infinite, the result is positive infinity. 1281 * <li>If the argument is NaN, the result is NaN.</ul> 1282 * 1283 * @apiNote As implied by the above, one valid implementation of 1284 * this method is given by the expression below which computes a 1285 * {@code double} with the same exponent and significand as the 1286 * argument but with a guaranteed zero sign bit indicating a 1287 * positive value: <br> 1288 * {@code Double.longBitsToDouble((Double.doubleToRawLongBits(a)<<1)>>>1)} 1289 * 1290 * @param a the argument whose absolute value is to be determined 1291 * @return the absolute value of the argument. 1292 */ abs(double a)1293 public static double abs(double a) { 1294 return Math.abs(a); 1295 } 1296 1297 /** 1298 * Returns the greater of two {@code int} values. That is, the 1299 * result is the argument closer to the value of 1300 * {@link Integer#MAX_VALUE}. If the arguments have the same value, 1301 * the result is that same value. 1302 * 1303 * @param a an argument. 1304 * @param b another argument. 1305 * @return the larger of {@code a} and {@code b}. 1306 */ 1307 @IntrinsicCandidate max(int a, int b)1308 public static int max(int a, int b) { 1309 return Math.max(a, b); 1310 } 1311 1312 /** 1313 * Returns the greater of two {@code long} values. That is, the 1314 * result is the argument closer to the value of 1315 * {@link Long#MAX_VALUE}. If the arguments have the same value, 1316 * the result is that same value. 1317 * 1318 * @param a an argument. 1319 * @param b another argument. 1320 * @return the larger of {@code a} and {@code b}. 1321 */ max(long a, long b)1322 public static long max(long a, long b) { 1323 return Math.max(a, b); 1324 } 1325 1326 /** 1327 * Returns the greater of two {@code float} values. That is, 1328 * the result is the argument closer to positive infinity. If the 1329 * arguments have the same value, the result is that same 1330 * value. If either value is NaN, then the result is NaN. Unlike 1331 * the numerical comparison operators, this method considers 1332 * negative zero to be strictly smaller than positive zero. If one 1333 * argument is positive zero and the other negative zero, the 1334 * result is positive zero. 1335 * 1336 * @param a an argument. 1337 * @param b another argument. 1338 * @return the larger of {@code a} and {@code b}. 1339 */ 1340 @IntrinsicCandidate max(float a, float b)1341 public static float max(float a, float b) { 1342 return Math.max(a, b); 1343 } 1344 1345 /** 1346 * Returns the greater of two {@code double} values. That 1347 * is, the result is the argument closer to positive infinity. If 1348 * the arguments have the same value, the result is that same 1349 * value. If either value is NaN, then the result is NaN. Unlike 1350 * the numerical comparison operators, this method considers 1351 * negative zero to be strictly smaller than positive zero. If one 1352 * argument is positive zero and the other negative zero, the 1353 * result is positive zero. 1354 * 1355 * @param a an argument. 1356 * @param b another argument. 1357 * @return the larger of {@code a} and {@code b}. 1358 */ 1359 @IntrinsicCandidate max(double a, double b)1360 public static double max(double a, double b) { 1361 return Math.max(a, b); 1362 } 1363 1364 /** 1365 * Returns the smaller of two {@code int} values. That is, 1366 * the result the argument closer to the value of 1367 * {@link Integer#MIN_VALUE}. If the arguments have the same 1368 * value, the result is that same value. 1369 * 1370 * @param a an argument. 1371 * @param b another argument. 1372 * @return the smaller of {@code a} and {@code b}. 1373 */ 1374 @IntrinsicCandidate min(int a, int b)1375 public static int min(int a, int b) { 1376 return Math.min(a, b); 1377 } 1378 1379 /** 1380 * Returns the smaller of two {@code long} values. That is, 1381 * the result is the argument closer to the value of 1382 * {@link Long#MIN_VALUE}. If the arguments have the same 1383 * value, the result is that same value. 1384 * 1385 * @param a an argument. 1386 * @param b another argument. 1387 * @return the smaller of {@code a} and {@code b}. 1388 */ min(long a, long b)1389 public static long min(long a, long b) { 1390 return Math.min(a, b); 1391 } 1392 1393 /** 1394 * Returns the smaller of two {@code float} values. That is, 1395 * the result is the value closer to negative infinity. If the 1396 * arguments have the same value, the result is that same 1397 * value. If either value is NaN, then the result is NaN. Unlike 1398 * the numerical comparison operators, this method considers 1399 * negative zero to be strictly smaller than positive zero. If 1400 * one argument is positive zero and the other is negative zero, 1401 * the result is negative zero. 1402 * 1403 * @param a an argument. 1404 * @param b another argument. 1405 * @return the smaller of {@code a} and {@code b.} 1406 */ 1407 @IntrinsicCandidate min(float a, float b)1408 public static float min(float a, float b) { 1409 return Math.min(a, b); 1410 } 1411 1412 /** 1413 * Returns the smaller of two {@code double} values. That 1414 * is, the result is the value closer to negative infinity. If the 1415 * arguments have the same value, the result is that same 1416 * value. If either value is NaN, then the result is NaN. Unlike 1417 * the numerical comparison operators, this method considers 1418 * negative zero to be strictly smaller than positive zero. If one 1419 * argument is positive zero and the other is negative zero, the 1420 * result is negative zero. 1421 * 1422 * @param a an argument. 1423 * @param b another argument. 1424 * @return the smaller of {@code a} and {@code b}. 1425 */ 1426 @IntrinsicCandidate min(double a, double b)1427 public static double min(double a, double b) { 1428 return Math.min(a, b); 1429 } 1430 1431 /** 1432 * Returns the fused multiply add of the three arguments; that is, 1433 * returns the exact product of the first two arguments summed 1434 * with the third argument and then rounded once to the nearest 1435 * {@code double}. 1436 * 1437 * The rounding is done using the {@linkplain 1438 * java.math.RoundingMode#HALF_EVEN round to nearest even 1439 * rounding mode}. 1440 * 1441 * In contrast, if {@code a * b + c} is evaluated as a regular 1442 * floating-point expression, two rounding errors are involved, 1443 * the first for the multiply operation, the second for the 1444 * addition operation. 1445 * 1446 * <p>Special cases: 1447 * <ul> 1448 * <li> If any argument is NaN, the result is NaN. 1449 * 1450 * <li> If one of the first two arguments is infinite and the 1451 * other is zero, the result is NaN. 1452 * 1453 * <li> If the exact product of the first two arguments is infinite 1454 * (in other words, at least one of the arguments is infinite and 1455 * the other is neither zero nor NaN) and the third argument is an 1456 * infinity of the opposite sign, the result is NaN. 1457 * 1458 * </ul> 1459 * 1460 * <p>Note that {@code fusedMac(a, 1.0, c)} returns the same 1461 * result as ({@code a + c}). However, 1462 * {@code fusedMac(a, b, +0.0)} does <em>not</em> always return the 1463 * same result as ({@code a * b}) since 1464 * {@code fusedMac(-0.0, +0.0, +0.0)} is {@code +0.0} while 1465 * ({@code -0.0 * +0.0}) is {@code -0.0}; {@code fusedMac(a, b, -0.0)} is 1466 * equivalent to ({@code a * b}) however. 1467 * 1468 * @apiNote This method corresponds to the fusedMultiplyAdd 1469 * operation defined in IEEE 754-2008. 1470 * 1471 * @param a a value 1472 * @param b a value 1473 * @param c a value 1474 * 1475 * @return (<i>a</i> × <i>b</i> + <i>c</i>) 1476 * computed, as if with unlimited range and precision, and rounded 1477 * once to the nearest {@code double} value 1478 * 1479 * @since 9 1480 */ fma(double a, double b, double c)1481 public static double fma(double a, double b, double c) { 1482 return Math.fma(a, b, c); 1483 } 1484 1485 /** 1486 * Returns the fused multiply add of the three arguments; that is, 1487 * returns the exact product of the first two arguments summed 1488 * with the third argument and then rounded once to the nearest 1489 * {@code float}. 1490 * 1491 * The rounding is done using the {@linkplain 1492 * java.math.RoundingMode#HALF_EVEN round to nearest even 1493 * rounding mode}. 1494 * 1495 * In contrast, if {@code a * b + c} is evaluated as a regular 1496 * floating-point expression, two rounding errors are involved, 1497 * the first for the multiply operation, the second for the 1498 * addition operation. 1499 * 1500 * <p>Special cases: 1501 * <ul> 1502 * <li> If any argument is NaN, the result is NaN. 1503 * 1504 * <li> If one of the first two arguments is infinite and the 1505 * other is zero, the result is NaN. 1506 * 1507 * <li> If the exact product of the first two arguments is infinite 1508 * (in other words, at least one of the arguments is infinite and 1509 * the other is neither zero nor NaN) and the third argument is an 1510 * infinity of the opposite sign, the result is NaN. 1511 * 1512 * </ul> 1513 * 1514 * <p>Note that {@code fma(a, 1.0f, c)} returns the same 1515 * result as ({@code a + c}). However, 1516 * {@code fma(a, b, +0.0f)} does <em>not</em> always return the 1517 * same result as ({@code a * b}) since 1518 * {@code fma(-0.0f, +0.0f, +0.0f)} is {@code +0.0f} while 1519 * ({@code -0.0f * +0.0f}) is {@code -0.0f}; {@code fma(a, b, -0.0f)} is 1520 * equivalent to ({@code a * b}) however. 1521 * 1522 * @apiNote This method corresponds to the fusedMultiplyAdd 1523 * operation defined in IEEE 754-2008. 1524 * 1525 * @param a a value 1526 * @param b a value 1527 * @param c a value 1528 * 1529 * @return (<i>a</i> × <i>b</i> + <i>c</i>) 1530 * computed, as if with unlimited range and precision, and rounded 1531 * once to the nearest {@code float} value 1532 * 1533 * @since 9 1534 */ fma(float a, float b, float c)1535 public static float fma(float a, float b, float c) { 1536 return Math.fma(a, b, c); 1537 } 1538 1539 /** 1540 * Returns the size of an ulp of the argument. An ulp, unit in 1541 * the last place, of a {@code double} value is the positive 1542 * distance between this floating-point value and the {@code 1543 * double} value next larger in magnitude. Note that for non-NaN 1544 * <i>x</i>, <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>. 1545 * 1546 * <p>Special Cases: 1547 * <ul> 1548 * <li> If the argument is NaN, then the result is NaN. 1549 * <li> If the argument is positive or negative infinity, then the 1550 * result is positive infinity. 1551 * <li> If the argument is positive or negative zero, then the result is 1552 * {@code Double.MIN_VALUE}. 1553 * <li> If the argument is ±{@code Double.MAX_VALUE}, then 1554 * the result is equal to 2<sup>971</sup>. 1555 * </ul> 1556 * 1557 * @param d the floating-point value whose ulp is to be returned 1558 * @return the size of an ulp of the argument 1559 * @author Joseph D. Darcy 1560 * @since 1.5 1561 */ ulp(double d)1562 public static double ulp(double d) { 1563 return Math.ulp(d); 1564 } 1565 1566 /** 1567 * Returns the size of an ulp of the argument. An ulp, unit in 1568 * the last place, of a {@code float} value is the positive 1569 * distance between this floating-point value and the {@code 1570 * float} value next larger in magnitude. Note that for non-NaN 1571 * <i>x</i>, <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>. 1572 * 1573 * <p>Special Cases: 1574 * <ul> 1575 * <li> If the argument is NaN, then the result is NaN. 1576 * <li> If the argument is positive or negative infinity, then the 1577 * result is positive infinity. 1578 * <li> If the argument is positive or negative zero, then the result is 1579 * {@code Float.MIN_VALUE}. 1580 * <li> If the argument is ±{@code Float.MAX_VALUE}, then 1581 * the result is equal to 2<sup>104</sup>. 1582 * </ul> 1583 * 1584 * @param f the floating-point value whose ulp is to be returned 1585 * @return the size of an ulp of the argument 1586 * @author Joseph D. Darcy 1587 * @since 1.5 1588 */ ulp(float f)1589 public static float ulp(float f) { 1590 return Math.ulp(f); 1591 } 1592 1593 /** 1594 * Returns the signum function of the argument; zero if the argument 1595 * is zero, 1.0 if the argument is greater than zero, -1.0 if the 1596 * argument is less than zero. 1597 * 1598 * <p>Special Cases: 1599 * <ul> 1600 * <li> If the argument is NaN, then the result is NaN. 1601 * <li> If the argument is positive zero or negative zero, then the 1602 * result is the same as the argument. 1603 * </ul> 1604 * 1605 * @param d the floating-point value whose signum is to be returned 1606 * @return the signum function of the argument 1607 * @author Joseph D. Darcy 1608 * @since 1.5 1609 */ signum(double d)1610 public static double signum(double d) { 1611 return Math.signum(d); 1612 } 1613 1614 /** 1615 * Returns the signum function of the argument; zero if the argument 1616 * is zero, 1.0f if the argument is greater than zero, -1.0f if the 1617 * argument is less than zero. 1618 * 1619 * <p>Special Cases: 1620 * <ul> 1621 * <li> If the argument is NaN, then the result is NaN. 1622 * <li> If the argument is positive zero or negative zero, then the 1623 * result is the same as the argument. 1624 * </ul> 1625 * 1626 * @param f the floating-point value whose signum is to be returned 1627 * @return the signum function of the argument 1628 * @author Joseph D. Darcy 1629 * @since 1.5 1630 */ signum(float f)1631 public static float signum(float f) { 1632 return Math.signum(f); 1633 } 1634 1635 /** 1636 * Returns the hyperbolic sine of a {@code double} value. 1637 * The hyperbolic sine of <i>x</i> is defined to be 1638 * (<i>e<sup>x</sup> - e<sup>-x</sup></i>)/2 1639 * where <i>e</i> is {@linkplain Math#E Euler's number}. 1640 * 1641 * <p>Special cases: 1642 * <ul> 1643 * 1644 * <li>If the argument is NaN, then the result is NaN. 1645 * 1646 * <li>If the argument is infinite, then the result is an infinity 1647 * with the same sign as the argument. 1648 * 1649 * <li>If the argument is zero, then the result is a zero with the 1650 * same sign as the argument. 1651 * 1652 * </ul> 1653 * 1654 * @param x The number whose hyperbolic sine is to be returned. 1655 * @return The hyperbolic sine of {@code x}. 1656 * @since 1.5 1657 */ sinh(double x)1658 public static native double sinh(double x); 1659 1660 /** 1661 * Returns the hyperbolic cosine of a {@code double} value. 1662 * The hyperbolic cosine of <i>x</i> is defined to be 1663 * (<i>e<sup>x</sup> + e<sup>-x</sup></i>)/2 1664 * where <i>e</i> is {@linkplain Math#E Euler's number}. 1665 * 1666 * <p>Special cases: 1667 * <ul> 1668 * 1669 * <li>If the argument is NaN, then the result is NaN. 1670 * 1671 * <li>If the argument is infinite, then the result is positive 1672 * infinity. 1673 * 1674 * <li>If the argument is zero, then the result is {@code 1.0}. 1675 * 1676 * </ul> 1677 * 1678 * @param x The number whose hyperbolic cosine is to be returned. 1679 * @return The hyperbolic cosine of {@code x}. 1680 * @since 1.5 1681 */ cosh(double x)1682 public static native double cosh(double x); 1683 1684 /** 1685 * Returns the hyperbolic tangent of a {@code double} value. 1686 * The hyperbolic tangent of <i>x</i> is defined to be 1687 * (<i>e<sup>x</sup> - e<sup>-x</sup></i>)/(<i>e<sup>x</sup> + e<sup>-x</sup></i>), 1688 * in other words, {@linkplain Math#sinh 1689 * sinh(<i>x</i>)}/{@linkplain Math#cosh cosh(<i>x</i>)}. Note 1690 * that the absolute value of the exact tanh is always less than 1691 * 1. 1692 * 1693 * <p>Special cases: 1694 * <ul> 1695 * 1696 * <li>If the argument is NaN, then the result is NaN. 1697 * 1698 * <li>If the argument is zero, then the result is a zero with the 1699 * same sign as the argument. 1700 * 1701 * <li>If the argument is positive infinity, then the result is 1702 * {@code +1.0}. 1703 * 1704 * <li>If the argument is negative infinity, then the result is 1705 * {@code -1.0}. 1706 * 1707 * </ul> 1708 * 1709 * @param x The number whose hyperbolic tangent is to be returned. 1710 * @return The hyperbolic tangent of {@code x}. 1711 * @since 1.5 1712 */ tanh(double x)1713 public static native double tanh(double x); 1714 1715 /** 1716 * Returns sqrt(<i>x</i><sup>2</sup> +<i>y</i><sup>2</sup>) 1717 * without intermediate overflow or underflow. 1718 * 1719 * <p>Special cases: 1720 * <ul> 1721 * 1722 * <li> If either argument is infinite, then the result 1723 * is positive infinity. 1724 * 1725 * <li> If either argument is NaN and neither argument is infinite, 1726 * then the result is NaN. 1727 * 1728 * <li> If both arguments are zero, the result is positive zero. 1729 * </ul> 1730 * 1731 * @param x a value 1732 * @param y a value 1733 * @return sqrt(<i>x</i><sup>2</sup> +<i>y</i><sup>2</sup>) 1734 * without intermediate overflow or underflow 1735 * @since 1.5 1736 */ 1737 // BEGIN Android-changed: Reimplement in native 1738 /* 1739 public static double hypot(double x, double y) { 1740 return FdLibm.Hypot.compute(x, y); 1741 } 1742 */ 1743 // END Android-changed: Reimplement in native hypot(double x, double y)1744 public static native double hypot(double x, double y); 1745 1746 /** 1747 * Returns <i>e</i><sup>x</sup> -1. Note that for values of 1748 * <i>x</i> near 0, the exact sum of 1749 * {@code expm1(x)} + 1 is much closer to the true 1750 * result of <i>e</i><sup>x</sup> than {@code exp(x)}. 1751 * 1752 * <p>Special cases: 1753 * <ul> 1754 * <li>If the argument is NaN, the result is NaN. 1755 * 1756 * <li>If the argument is positive infinity, then the result is 1757 * positive infinity. 1758 * 1759 * <li>If the argument is negative infinity, then the result is 1760 * -1.0. 1761 * 1762 * <li>If the argument is zero, then the result is a zero with the 1763 * same sign as the argument. 1764 * 1765 * </ul> 1766 * 1767 * @param x the exponent to raise <i>e</i> to in the computation of 1768 * <i>e</i><sup>{@code x}</sup> -1. 1769 * @return the value <i>e</i><sup>{@code x}</sup> - 1. 1770 * @since 1.5 1771 */ expm1(double x)1772 public static native double expm1(double x); 1773 1774 /** 1775 * Returns the natural logarithm of the sum of the argument and 1. 1776 * Note that for small values {@code x}, the result of 1777 * {@code log1p(x)} is much closer to the true result of ln(1 1778 * + {@code x}) than the floating-point evaluation of 1779 * {@code log(1.0+x)}. 1780 * 1781 * <p>Special cases: 1782 * <ul> 1783 * 1784 * <li>If the argument is NaN or less than -1, then the result is 1785 * NaN. 1786 * 1787 * <li>If the argument is positive infinity, then the result is 1788 * positive infinity. 1789 * 1790 * <li>If the argument is negative one, then the result is 1791 * negative infinity. 1792 * 1793 * <li>If the argument is zero, then the result is a zero with the 1794 * same sign as the argument. 1795 * 1796 * </ul> 1797 * 1798 * @param x a value 1799 * @return the value ln({@code x} + 1), the natural 1800 * log of {@code x} + 1 1801 * @since 1.5 1802 */ log1p(double x)1803 public static native double log1p(double x); 1804 1805 /** 1806 * Returns the first floating-point argument with the sign of the 1807 * second floating-point argument. For this method, a NaN 1808 * {@code sign} argument is always treated as if it were 1809 * positive. 1810 * 1811 * @param magnitude the parameter providing the magnitude of the result 1812 * @param sign the parameter providing the sign of the result 1813 * @return a value with the magnitude of {@code magnitude} 1814 * and the sign of {@code sign}. 1815 * @since 1.6 1816 */ copySign(double magnitude, double sign)1817 public static double copySign(double magnitude, double sign) { 1818 return Math.copySign(magnitude, (Double.isNaN(sign)?1.0d:sign)); 1819 } 1820 1821 /** 1822 * Returns the first floating-point argument with the sign of the 1823 * second floating-point argument. For this method, a NaN 1824 * {@code sign} argument is always treated as if it were 1825 * positive. 1826 * 1827 * @param magnitude the parameter providing the magnitude of the result 1828 * @param sign the parameter providing the sign of the result 1829 * @return a value with the magnitude of {@code magnitude} 1830 * and the sign of {@code sign}. 1831 * @since 1.6 1832 */ copySign(float magnitude, float sign)1833 public static float copySign(float magnitude, float sign) { 1834 return Math.copySign(magnitude, (Float.isNaN(sign)?1.0f:sign)); 1835 } 1836 /** 1837 * Returns the unbiased exponent used in the representation of a 1838 * {@code float}. Special cases: 1839 * 1840 * <ul> 1841 * <li>If the argument is NaN or infinite, then the result is 1842 * {@link Float#MAX_EXPONENT} + 1. 1843 * <li>If the argument is zero or subnormal, then the result is 1844 * {@link Float#MIN_EXPONENT} -1. 1845 * </ul> 1846 * @param f a {@code float} value 1847 * @return the unbiased exponent of the argument 1848 * @since 1.6 1849 */ getExponent(float f)1850 public static int getExponent(float f) { 1851 return Math.getExponent(f); 1852 } 1853 1854 /** 1855 * Returns the unbiased exponent used in the representation of a 1856 * {@code double}. Special cases: 1857 * 1858 * <ul> 1859 * <li>If the argument is NaN or infinite, then the result is 1860 * {@link Double#MAX_EXPONENT} + 1. 1861 * <li>If the argument is zero or subnormal, then the result is 1862 * {@link Double#MIN_EXPONENT} -1. 1863 * </ul> 1864 * @param d a {@code double} value 1865 * @return the unbiased exponent of the argument 1866 * @since 1.6 1867 */ getExponent(double d)1868 public static int getExponent(double d) { 1869 return Math.getExponent(d); 1870 } 1871 1872 /** 1873 * Returns the floating-point number adjacent to the first 1874 * argument in the direction of the second argument. If both 1875 * arguments compare as equal the second argument is returned. 1876 * 1877 * <p>Special cases: 1878 * <ul> 1879 * <li> If either argument is a NaN, then NaN is returned. 1880 * 1881 * <li> If both arguments are signed zeros, {@code direction} 1882 * is returned unchanged (as implied by the requirement of 1883 * returning the second argument if the arguments compare as 1884 * equal). 1885 * 1886 * <li> If {@code start} is 1887 * ±{@link Double#MIN_VALUE} and {@code direction} 1888 * has a value such that the result should have a smaller 1889 * magnitude, then a zero with the same sign as {@code start} 1890 * is returned. 1891 * 1892 * <li> If {@code start} is infinite and 1893 * {@code direction} has a value such that the result should 1894 * have a smaller magnitude, {@link Double#MAX_VALUE} with the 1895 * same sign as {@code start} is returned. 1896 * 1897 * <li> If {@code start} is equal to ± 1898 * {@link Double#MAX_VALUE} and {@code direction} has a 1899 * value such that the result should have a larger magnitude, an 1900 * infinity with same sign as {@code start} is returned. 1901 * </ul> 1902 * 1903 * @param start starting floating-point value 1904 * @param direction value indicating which of 1905 * {@code start}'s neighbors or {@code start} should 1906 * be returned 1907 * @return The floating-point number adjacent to {@code start} in the 1908 * direction of {@code direction}. 1909 * @since 1.6 1910 */ nextAfter(double start, double direction)1911 public static double nextAfter(double start, double direction) { 1912 return Math.nextAfter(start, direction); 1913 } 1914 1915 /** 1916 * Returns the floating-point number adjacent to the first 1917 * argument in the direction of the second argument. If both 1918 * arguments compare as equal a value equivalent to the second argument 1919 * is returned. 1920 * 1921 * <p>Special cases: 1922 * <ul> 1923 * <li> If either argument is a NaN, then NaN is returned. 1924 * 1925 * <li> If both arguments are signed zeros, a value equivalent 1926 * to {@code direction} is returned. 1927 * 1928 * <li> If {@code start} is 1929 * ±{@link Float#MIN_VALUE} and {@code direction} 1930 * has a value such that the result should have a smaller 1931 * magnitude, then a zero with the same sign as {@code start} 1932 * is returned. 1933 * 1934 * <li> If {@code start} is infinite and 1935 * {@code direction} has a value such that the result should 1936 * have a smaller magnitude, {@link Float#MAX_VALUE} with the 1937 * same sign as {@code start} is returned. 1938 * 1939 * <li> If {@code start} is equal to ± 1940 * {@link Float#MAX_VALUE} and {@code direction} has a 1941 * value such that the result should have a larger magnitude, an 1942 * infinity with same sign as {@code start} is returned. 1943 * </ul> 1944 * 1945 * @param start starting floating-point value 1946 * @param direction value indicating which of 1947 * {@code start}'s neighbors or {@code start} should 1948 * be returned 1949 * @return The floating-point number adjacent to {@code start} in the 1950 * direction of {@code direction}. 1951 * @since 1.6 1952 */ nextAfter(float start, double direction)1953 public static float nextAfter(float start, double direction) { 1954 return Math.nextAfter(start, direction); 1955 } 1956 1957 /** 1958 * Returns the floating-point value adjacent to {@code d} in 1959 * the direction of positive infinity. This method is 1960 * semantically equivalent to {@code nextAfter(d, 1961 * Double.POSITIVE_INFINITY)}; however, a {@code nextUp} 1962 * implementation may run faster than its equivalent 1963 * {@code nextAfter} call. 1964 * 1965 * <p>Special Cases: 1966 * <ul> 1967 * <li> If the argument is NaN, the result is NaN. 1968 * 1969 * <li> If the argument is positive infinity, the result is 1970 * positive infinity. 1971 * 1972 * <li> If the argument is zero, the result is 1973 * {@link Double#MIN_VALUE} 1974 * 1975 * </ul> 1976 * 1977 * @param d starting floating-point value 1978 * @return The adjacent floating-point value closer to positive 1979 * infinity. 1980 * @since 1.6 1981 */ nextUp(double d)1982 public static double nextUp(double d) { 1983 return Math.nextUp(d); 1984 } 1985 1986 /** 1987 * Returns the floating-point value adjacent to {@code f} in 1988 * the direction of positive infinity. This method is 1989 * semantically equivalent to {@code nextAfter(f, 1990 * Float.POSITIVE_INFINITY)}; however, a {@code nextUp} 1991 * implementation may run faster than its equivalent 1992 * {@code nextAfter} call. 1993 * 1994 * <p>Special Cases: 1995 * <ul> 1996 * <li> If the argument is NaN, the result is NaN. 1997 * 1998 * <li> If the argument is positive infinity, the result is 1999 * positive infinity. 2000 * 2001 * <li> If the argument is zero, the result is 2002 * {@link Float#MIN_VALUE} 2003 * 2004 * </ul> 2005 * 2006 * @param f starting floating-point value 2007 * @return The adjacent floating-point value closer to positive 2008 * infinity. 2009 * @since 1.6 2010 */ nextUp(float f)2011 public static float nextUp(float f) { 2012 return Math.nextUp(f); 2013 } 2014 2015 /** 2016 * Returns the floating-point value adjacent to {@code d} in 2017 * the direction of negative infinity. This method is 2018 * semantically equivalent to {@code nextAfter(d, 2019 * Double.NEGATIVE_INFINITY)}; however, a 2020 * {@code nextDown} implementation may run faster than its 2021 * equivalent {@code nextAfter} call. 2022 * 2023 * <p>Special Cases: 2024 * <ul> 2025 * <li> If the argument is NaN, the result is NaN. 2026 * 2027 * <li> If the argument is negative infinity, the result is 2028 * negative infinity. 2029 * 2030 * <li> If the argument is zero, the result is 2031 * {@code -Double.MIN_VALUE} 2032 * 2033 * </ul> 2034 * 2035 * @param d starting floating-point value 2036 * @return The adjacent floating-point value closer to negative 2037 * infinity. 2038 * @since 1.8 2039 */ nextDown(double d)2040 public static double nextDown(double d) { 2041 return Math.nextDown(d); 2042 } 2043 2044 /** 2045 * Returns the floating-point value adjacent to {@code f} in 2046 * the direction of negative infinity. This method is 2047 * semantically equivalent to {@code nextAfter(f, 2048 * Float.NEGATIVE_INFINITY)}; however, a 2049 * {@code nextDown} implementation may run faster than its 2050 * equivalent {@code nextAfter} call. 2051 * 2052 * <p>Special Cases: 2053 * <ul> 2054 * <li> If the argument is NaN, the result is NaN. 2055 * 2056 * <li> If the argument is negative infinity, the result is 2057 * negative infinity. 2058 * 2059 * <li> If the argument is zero, the result is 2060 * {@code -Float.MIN_VALUE} 2061 * 2062 * </ul> 2063 * 2064 * @param f starting floating-point value 2065 * @return The adjacent floating-point value closer to negative 2066 * infinity. 2067 * @since 1.8 2068 */ nextDown(float f)2069 public static float nextDown(float f) { 2070 return Math.nextDown(f); 2071 } 2072 2073 /** 2074 * Returns {@code d} × 2<sup>{@code scaleFactor}</sup> 2075 * rounded as if performed by a single correctly rounded 2076 * floating-point multiply. If the exponent of the result is 2077 * between {@link Double#MIN_EXPONENT} and {@link 2078 * Double#MAX_EXPONENT}, the answer is calculated exactly. If the 2079 * exponent of the result would be larger than {@code 2080 * Double.MAX_EXPONENT}, an infinity is returned. Note that if 2081 * the result is subnormal, precision may be lost; that is, when 2082 * {@code scalb(x, n)} is subnormal, {@code scalb(scalb(x, n), 2083 * -n)} may not equal <i>x</i>. When the result is non-NaN, the 2084 * result has the same sign as {@code d}. 2085 * 2086 * <p>Special cases: 2087 * <ul> 2088 * <li> If the first argument is NaN, NaN is returned. 2089 * <li> If the first argument is infinite, then an infinity of the 2090 * same sign is returned. 2091 * <li> If the first argument is zero, then a zero of the same 2092 * sign is returned. 2093 * </ul> 2094 * 2095 * @param d number to be scaled by a power of two. 2096 * @param scaleFactor power of 2 used to scale {@code d} 2097 * @return {@code d} × 2<sup>{@code scaleFactor}</sup> 2098 * @since 1.6 2099 */ scalb(double d, int scaleFactor)2100 public static double scalb(double d, int scaleFactor) { 2101 return Math.scalb(d, scaleFactor); 2102 } 2103 2104 /** 2105 * Returns {@code f} × 2<sup>{@code scaleFactor}</sup> 2106 * rounded as if performed by a single correctly rounded 2107 * floating-point multiply. If the exponent of the result is 2108 * between {@link Float#MIN_EXPONENT} and {@link 2109 * Float#MAX_EXPONENT}, the answer is calculated exactly. If the 2110 * exponent of the result would be larger than {@code 2111 * Float.MAX_EXPONENT}, an infinity is returned. Note that if the 2112 * result is subnormal, precision may be lost; that is, when 2113 * {@code scalb(x, n)} is subnormal, {@code scalb(scalb(x, n), 2114 * -n)} may not equal <i>x</i>. When the result is non-NaN, the 2115 * result has the same sign as {@code f}. 2116 * 2117 * <p>Special cases: 2118 * <ul> 2119 * <li> If the first argument is NaN, NaN is returned. 2120 * <li> If the first argument is infinite, then an infinity of the 2121 * same sign is returned. 2122 * <li> If the first argument is zero, then a zero of the same 2123 * sign is returned. 2124 * </ul> 2125 * 2126 * @param f number to be scaled by a power of two. 2127 * @param scaleFactor power of 2 used to scale {@code f} 2128 * @return {@code f} × 2<sup>{@code scaleFactor}</sup> 2129 * @since 1.6 2130 */ scalb(float f, int scaleFactor)2131 public static float scalb(float f, int scaleFactor) { 2132 return Math.scalb(f, scaleFactor); 2133 } 2134 } 2135