1 /* 2 * Copyright (c) 1994, 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 28 import java.util.Random; 29 import sun.misc.FloatConsts; 30 import sun.misc.DoubleConsts; 31 import jdk.internal.HotSpotIntrinsicCandidate; 32 33 /** 34 * The class {@code Math} contains methods for performing basic 35 * numeric operations such as the elementary exponential, logarithm, 36 * square root, and trigonometric functions. 37 * 38 * <p>Unlike some of the numeric methods of class 39 * {@code StrictMath}, all implementations of the equivalent 40 * functions of class {@code Math} are not defined to return the 41 * bit-for-bit same results. This relaxation permits 42 * better-performing implementations where strict reproducibility is 43 * not required. 44 * 45 * <p>By default many of the {@code Math} methods simply call 46 * the equivalent method in {@code StrictMath} for their 47 * implementation. Code generators are encouraged to use 48 * platform-specific native libraries or microprocessor instructions, 49 * where available, to provide higher-performance implementations of 50 * {@code Math} methods. Such higher-performance 51 * implementations still must conform to the specification for 52 * {@code Math}. 53 * 54 * <p>The quality of implementation specifications concern two 55 * properties, accuracy of the returned result and monotonicity of the 56 * method. Accuracy of the floating-point {@code Math} methods is 57 * measured in terms of <i>ulps</i>, units in the last place. For a 58 * given floating-point format, an {@linkplain #ulp(double) ulp} of a 59 * specific real number value is the distance between the two 60 * floating-point values bracketing that numerical value. When 61 * discussing the accuracy of a method as a whole rather than at a 62 * specific argument, the number of ulps cited is for the worst-case 63 * error at any argument. If a method always has an error less than 64 * 0.5 ulps, the method always returns the floating-point number 65 * nearest the exact result; such a method is <i>correctly 66 * rounded</i>. A correctly rounded method is generally the best a 67 * floating-point approximation can be; however, it is impractical for 68 * many floating-point methods to be correctly rounded. Instead, for 69 * the {@code Math} class, a larger error bound of 1 or 2 ulps is 70 * allowed for certain methods. Informally, with a 1 ulp error bound, 71 * when the exact result is a representable number, the exact result 72 * should be returned as the computed result; otherwise, either of the 73 * two floating-point values which bracket the exact result may be 74 * returned. For exact results large in magnitude, one of the 75 * endpoints of the bracket may be infinite. Besides accuracy at 76 * individual arguments, maintaining proper relations between the 77 * method at different arguments is also important. Therefore, most 78 * methods with more than 0.5 ulp errors are required to be 79 * <i>semi-monotonic</i>: whenever the mathematical function is 80 * non-decreasing, so is the floating-point approximation, likewise, 81 * whenever the mathematical function is non-increasing, so is the 82 * floating-point approximation. Not all approximations that have 1 83 * ulp accuracy will automatically meet the monotonicity requirements. 84 * 85 * <p> 86 * The platform uses signed two's complement integer arithmetic with 87 * int and long primitive types. The developer should choose 88 * the primitive type to ensure that arithmetic operations consistently 89 * produce correct results, which in some cases means the operations 90 * will not overflow the range of values of the computation. 91 * The best practice is to choose the primitive type and algorithm to avoid 92 * overflow. In cases where the size is {@code int} or {@code long} and 93 * overflow errors need to be detected, the methods {@code addExact}, 94 * {@code subtractExact}, {@code multiplyExact}, and {@code toIntExact} 95 * throw an {@code ArithmeticException} when the results overflow. 96 * For other arithmetic operations such as divide, absolute value, 97 * increment, decrement, and negation overflow occurs only with 98 * a specific minimum or maximum value and should be checked against 99 * the minimum or maximum as appropriate. 100 * 101 * @author unascribed 102 * @author Joseph D. Darcy 103 * @since 1.0 104 */ 105 106 public final class Math { 107 108 /** 109 * Don't let anyone instantiate this class. 110 */ 111 private Math() {} 112 113 /** 114 * The {@code double} value that is closer than any other to 115 * <i>e</i>, the base of the natural logarithms. 116 */ 117 public static final double E = 2.7182818284590452354; 118 119 /** 120 * The {@code double} value that is closer than any other to 121 * <i>pi</i>, the ratio of the circumference of a circle to its 122 * diameter. 123 */ 124 public static final double PI = 3.14159265358979323846; 125 126 /** 127 * Constant by which to multiply an angular value in degrees to obtain an 128 * angular value in radians. 129 */ 130 private static final double DEGREES_TO_RADIANS = 0.017453292519943295; 131 132 /** 133 * Constant by which to multiply an angular value in radians to obtain an 134 * angular value in degrees. 135 */ 136 private static final double RADIANS_TO_DEGREES = 57.29577951308232; 137 138 /** 139 * Returns the trigonometric sine of an angle. Special cases: 140 * <ul><li>If the argument is NaN or an infinity, then the 141 * result is NaN. 142 * <li>If the argument is zero, then the result is a zero with the 143 * same sign as the argument.</ul> 144 * 145 * <p>The computed result must be within 1 ulp of the exact result. 146 * Results must be semi-monotonic. 147 * 148 * @param a an angle, in radians. 149 * @return the sine of the argument. 150 */ 151 @HotSpotIntrinsicCandidate 152 public static double sin(double a) { 153 return StrictMath.sin(a); // default impl. delegates to StrictMath 154 } 155 156 /** 157 * Returns the trigonometric cosine of an angle. Special cases: 158 * <ul><li>If the argument is NaN or an infinity, then the 159 * result is NaN.</ul> 160 * 161 * <p>The computed result must be within 1 ulp of the exact result. 162 * Results must be semi-monotonic. 163 * 164 * @param a an angle, in radians. 165 * @return the cosine of the argument. 166 */ 167 @HotSpotIntrinsicCandidate 168 public static double cos(double a) { 169 return StrictMath.cos(a); // default impl. delegates to StrictMath 170 } 171 172 /** 173 * Returns the trigonometric tangent of an angle. Special cases: 174 * <ul><li>If the argument is NaN or an infinity, then the result 175 * is NaN. 176 * <li>If the argument is zero, then the result is a zero with the 177 * same sign as the argument.</ul> 178 * 179 * <p>The computed result must be within 1 ulp of the exact result. 180 * Results must be semi-monotonic. 181 * 182 * @param a an angle, in radians. 183 * @return the tangent of the argument. 184 */ 185 @HotSpotIntrinsicCandidate 186 public static double tan(double a) { 187 return StrictMath.tan(a); // default impl. delegates to StrictMath 188 } 189 190 /** 191 * Returns the arc sine of a value; the returned angle is in the 192 * range -<i>pi</i>/2 through <i>pi</i>/2. Special cases: 193 * <ul><li>If the argument is NaN or its absolute value is greater 194 * than 1, then the result is NaN. 195 * <li>If the argument is zero, then the result is a zero with the 196 * same sign as the argument.</ul> 197 * 198 * <p>The computed result must be within 1 ulp of the exact result. 199 * Results must be semi-monotonic. 200 * 201 * @param a the value whose arc sine is to be returned. 202 * @return the arc sine of the argument. 203 */ 204 public static double asin(double a) { 205 return StrictMath.asin(a); // default impl. delegates to StrictMath 206 } 207 208 /** 209 * Returns the arc cosine of a value; the returned angle is in the 210 * range 0.0 through <i>pi</i>. Special case: 211 * <ul><li>If the argument is NaN or its absolute value is greater 212 * than 1, then the result is NaN.</ul> 213 * 214 * <p>The computed result must be within 1 ulp of the exact result. 215 * Results must be semi-monotonic. 216 * 217 * @param a the value whose arc cosine is to be returned. 218 * @return the arc cosine of the argument. 219 */ 220 public static double acos(double a) { 221 return StrictMath.acos(a); // default impl. delegates to StrictMath 222 } 223 224 /** 225 * Returns the arc tangent of a value; the returned angle is in the 226 * range -<i>pi</i>/2 through <i>pi</i>/2. Special cases: 227 * <ul><li>If the argument is NaN, then the result is NaN. 228 * <li>If the argument is zero, then the result is a zero with the 229 * same sign as the argument.</ul> 230 * 231 * <p>The computed result must be within 1 ulp of the exact result. 232 * Results must be semi-monotonic. 233 * 234 * @param a the value whose arc tangent is to be returned. 235 * @return the arc tangent of the argument. 236 */ 237 public static double atan(double a) { 238 return StrictMath.atan(a); // default impl. delegates to StrictMath 239 } 240 241 /** 242 * Converts an angle measured in degrees to an approximately 243 * equivalent angle measured in radians. The conversion from 244 * degrees to radians is generally inexact. 245 * 246 * @param angdeg an angle, in degrees 247 * @return the measurement of the angle {@code angdeg} 248 * in radians. 249 * @since 1.2 250 */ 251 public static double toRadians(double angdeg) { 252 return angdeg * DEGREES_TO_RADIANS; 253 } 254 255 /** 256 * Converts an angle measured in radians to an approximately 257 * equivalent angle measured in degrees. The conversion from 258 * radians to degrees is generally inexact; users should 259 * <i>not</i> expect {@code cos(toRadians(90.0))} to exactly 260 * equal {@code 0.0}. 261 * 262 * @param angrad an angle, in radians 263 * @return the measurement of the angle {@code angrad} 264 * in degrees. 265 * @since 1.2 266 */ 267 public static double toDegrees(double angrad) { 268 return angrad * RADIANS_TO_DEGREES; 269 } 270 271 /** 272 * Returns Euler's number <i>e</i> raised to the power of a 273 * {@code double} value. Special cases: 274 * <ul><li>If the argument is NaN, the result is NaN. 275 * <li>If the argument is positive infinity, then the result is 276 * positive infinity. 277 * <li>If the argument is negative infinity, then the result is 278 * positive zero.</ul> 279 * 280 * <p>The computed result must be within 1 ulp of the exact result. 281 * Results must be semi-monotonic. 282 * 283 * @param a the exponent to raise <i>e</i> to. 284 * @return the value <i>e</i><sup>{@code a}</sup>, 285 * where <i>e</i> is the base of the natural logarithms. 286 */ 287 @HotSpotIntrinsicCandidate 288 public static double exp(double a) { 289 return StrictMath.exp(a); // default impl. delegates to StrictMath 290 } 291 292 /** 293 * Returns the natural logarithm (base <i>e</i>) of a {@code double} 294 * value. Special cases: 295 * <ul><li>If the argument is NaN or less than zero, then the result 296 * is NaN. 297 * <li>If the argument is positive infinity, then the result is 298 * positive infinity. 299 * <li>If the argument is positive zero or negative zero, then the 300 * result is negative infinity.</ul> 301 * 302 * <p>The computed result must be within 1 ulp of the exact result. 303 * Results must be semi-monotonic. 304 * 305 * @param a a value 306 * @return the value ln {@code a}, the natural logarithm of 307 * {@code a}. 308 */ 309 @HotSpotIntrinsicCandidate 310 public static double log(double a) { 311 return StrictMath.log(a); // default impl. delegates to StrictMath 312 } 313 314 /** 315 * Returns the base 10 logarithm of a {@code double} value. 316 * Special cases: 317 * 318 * <ul><li>If the argument is NaN or less than zero, then the result 319 * is NaN. 320 * <li>If the argument is positive infinity, then the result is 321 * positive infinity. 322 * <li>If the argument is positive zero or negative zero, then the 323 * result is negative infinity. 324 * <li> If the argument is equal to 10<sup><i>n</i></sup> for 325 * integer <i>n</i>, then the result is <i>n</i>. 326 * </ul> 327 * 328 * <p>The computed result must be within 1 ulp of the exact result. 329 * Results must be semi-monotonic. 330 * 331 * @param a a value 332 * @return the base 10 logarithm of {@code a}. 333 * @since 1.5 334 */ 335 @HotSpotIntrinsicCandidate 336 public static double log10(double a) { 337 return StrictMath.log10(a); // default impl. delegates to StrictMath 338 } 339 340 /** 341 * Returns the correctly rounded positive square root of a 342 * {@code double} value. 343 * Special cases: 344 * <ul><li>If the argument is NaN or less than zero, then the result 345 * is NaN. 346 * <li>If the argument is positive infinity, then the result is positive 347 * infinity. 348 * <li>If the argument is positive zero or negative zero, then the 349 * result is the same as the argument.</ul> 350 * Otherwise, the result is the {@code double} value closest to 351 * the true mathematical square root of the argument value. 352 * 353 * @param a a value. 354 * @return the positive square root of {@code a}. 355 * If the argument is NaN or less than zero, the result is NaN. 356 */ 357 @HotSpotIntrinsicCandidate 358 public static double sqrt(double a) { 359 return StrictMath.sqrt(a); // default impl. delegates to StrictMath 360 // Note that hardware sqrt instructions 361 // frequently can be directly used by JITs 362 // and should be much faster than doing 363 // Math.sqrt in software. 364 } 365 366 367 /** 368 * Returns the cube root of a {@code double} value. For 369 * positive finite {@code x}, {@code cbrt(-x) == 370 * -cbrt(x)}; that is, the cube root of a negative value is 371 * the negative of the cube root of that value's magnitude. 372 * 373 * Special cases: 374 * 375 * <ul> 376 * 377 * <li>If the argument is NaN, then the result is NaN. 378 * 379 * <li>If the argument is infinite, then the result is an infinity 380 * with the same sign as the argument. 381 * 382 * <li>If the argument is zero, then the result is a zero with the 383 * same sign as the argument. 384 * 385 * </ul> 386 * 387 * <p>The computed result must be within 1 ulp of the exact result. 388 * 389 * @param a a value. 390 * @return the cube root of {@code a}. 391 * @since 1.5 392 */ 393 public static double cbrt(double a) { 394 return StrictMath.cbrt(a); 395 } 396 397 /** 398 * Computes the remainder operation on two arguments as prescribed 399 * by the IEEE 754 standard. 400 * The remainder value is mathematically equal to 401 * <code>f1 - f2</code> × <i>n</i>, 402 * where <i>n</i> is the mathematical integer closest to the exact 403 * mathematical value of the quotient {@code f1/f2}, and if two 404 * mathematical integers are equally close to {@code f1/f2}, 405 * then <i>n</i> is the integer that is even. If the remainder is 406 * zero, its sign is the same as the sign of the first argument. 407 * Special cases: 408 * <ul><li>If either argument is NaN, or the first argument is infinite, 409 * or the second argument is positive zero or negative zero, then the 410 * result is NaN. 411 * <li>If the first argument is finite and the second argument is 412 * infinite, then the result is the same as the first argument.</ul> 413 * 414 * @param f1 the dividend. 415 * @param f2 the divisor. 416 * @return the remainder when {@code f1} is divided by 417 * {@code f2}. 418 */ 419 public static double IEEEremainder(double f1, double f2) { 420 return StrictMath.IEEEremainder(f1, f2); // delegate to StrictMath 421 } 422 423 /** 424 * Returns the smallest (closest to negative infinity) 425 * {@code double} value that is greater than or equal to the 426 * argument and is equal to a mathematical integer. Special cases: 427 * <ul><li>If the argument value is already equal to a 428 * mathematical integer, then the result is the same as the 429 * argument. <li>If the argument is NaN or an infinity or 430 * positive zero or negative zero, then the result is the same as 431 * the argument. <li>If the argument value is less than zero but 432 * greater than -1.0, then the result is negative zero.</ul> Note 433 * that the value of {@code Math.ceil(x)} is exactly the 434 * value of {@code -Math.floor(-x)}. 435 * 436 * 437 * @param a a value. 438 * @return the smallest (closest to negative infinity) 439 * floating-point value that is greater than or equal to 440 * the argument and is equal to a mathematical integer. 441 */ 442 public static double ceil(double a) { 443 return StrictMath.ceil(a); // default impl. delegates to StrictMath 444 } 445 446 /** 447 * Returns the largest (closest to positive infinity) 448 * {@code double} value that is less than or equal to the 449 * argument and is equal to a mathematical integer. Special cases: 450 * <ul><li>If the argument value is already equal to a 451 * mathematical integer, then the result is the same as the 452 * argument. <li>If the argument is NaN or an infinity or 453 * positive zero or negative zero, then the result is the same as 454 * the argument.</ul> 455 * 456 * @param a a value. 457 * @return the largest (closest to positive infinity) 458 * floating-point value that less than or equal to the argument 459 * and is equal to a mathematical integer. 460 */ 461 public static double floor(double a) { 462 return StrictMath.floor(a); // default impl. delegates to StrictMath 463 } 464 465 /** 466 * Returns the {@code double} value that is closest in value 467 * to the argument and is equal to a mathematical integer. If two 468 * {@code double} values that are mathematical integers are 469 * equally close, the result is the integer value that is 470 * even. Special cases: 471 * <ul><li>If the argument value is already equal to a mathematical 472 * integer, then the result is the same as the argument. 473 * <li>If the argument is NaN or an infinity or positive zero or negative 474 * zero, then the result is the same as the argument.</ul> 475 * 476 * @param a a {@code double} value. 477 * @return the closest floating-point value to {@code a} that is 478 * equal to a mathematical integer. 479 */ 480 public static double rint(double a) { 481 return StrictMath.rint(a); // default impl. delegates to StrictMath 482 } 483 484 /** 485 * Returns the angle <i>theta</i> from the conversion of rectangular 486 * coordinates ({@code x}, {@code y}) to polar 487 * coordinates (r, <i>theta</i>). 488 * This method computes the phase <i>theta</i> by computing an arc tangent 489 * of {@code y/x} in the range of -<i>pi</i> to <i>pi</i>. Special 490 * cases: 491 * <ul><li>If either argument is NaN, then the result is NaN. 492 * <li>If the first argument is positive zero and the second argument 493 * is positive, or the first argument is positive and finite and the 494 * second argument is positive infinity, then the result is positive 495 * zero. 496 * <li>If the first argument is negative zero and the second argument 497 * is positive, or the first argument is negative and finite and the 498 * second argument is positive infinity, then the result is negative zero. 499 * <li>If the first argument is positive zero and the second argument 500 * is negative, or the first argument is positive and finite and the 501 * second argument is negative infinity, then the result is the 502 * {@code double} value closest to <i>pi</i>. 503 * <li>If the first argument is negative zero and the second argument 504 * is negative, or the first argument is negative and finite and the 505 * second argument is negative infinity, then the result is the 506 * {@code double} value closest to -<i>pi</i>. 507 * <li>If the first argument is positive and the second argument is 508 * positive zero or negative zero, or the first argument is positive 509 * infinity and the second argument is finite, then the result is the 510 * {@code double} value closest to <i>pi</i>/2. 511 * <li>If the first argument is negative and the second argument is 512 * positive zero or negative zero, or the first argument is negative 513 * infinity and the second argument is finite, then the result is the 514 * {@code double} value closest to -<i>pi</i>/2. 515 * <li>If both arguments are positive infinity, then the result is the 516 * {@code double} value closest to <i>pi</i>/4. 517 * <li>If the first argument is positive infinity and the second argument 518 * is negative infinity, then the result is the {@code double} 519 * value closest to 3*<i>pi</i>/4. 520 * <li>If the first argument is negative infinity and the second argument 521 * is positive infinity, then the result is the {@code double} value 522 * closest to -<i>pi</i>/4. 523 * <li>If both arguments are negative infinity, then the result is the 524 * {@code double} value closest to -3*<i>pi</i>/4.</ul> 525 * 526 * <p>The computed result must be within 2 ulps of the exact result. 527 * Results must be semi-monotonic. 528 * 529 * @param y the ordinate coordinate 530 * @param x the abscissa coordinate 531 * @return the <i>theta</i> component of the point 532 * (<i>r</i>, <i>theta</i>) 533 * in polar coordinates that corresponds to the point 534 * (<i>x</i>, <i>y</i>) in Cartesian coordinates. 535 */ 536 @HotSpotIntrinsicCandidate 537 public static double atan2(double y, double x) { 538 return StrictMath.atan2(y, x); // default impl. delegates to StrictMath 539 } 540 541 /** 542 * Returns the value of the first argument raised to the power of the 543 * second argument. Special cases: 544 * 545 * <ul><li>If the second argument is positive or negative zero, then the 546 * result is 1.0. 547 * <li>If the second argument is 1.0, then the result is the same as the 548 * first argument. 549 * <li>If the second argument is NaN, then the result is NaN. 550 * <li>If the first argument is NaN and the second argument is nonzero, 551 * then the result is NaN. 552 * 553 * <li>If 554 * <ul> 555 * <li>the absolute value of the first argument is greater than 1 556 * and the second argument is positive infinity, or 557 * <li>the absolute value of the first argument is less than 1 and 558 * the second argument is negative infinity, 559 * </ul> 560 * then the result is positive infinity. 561 * 562 * <li>If 563 * <ul> 564 * <li>the absolute value of the first argument is greater than 1 and 565 * the second argument is negative infinity, or 566 * <li>the absolute value of the 567 * first argument is less than 1 and the second argument is positive 568 * infinity, 569 * </ul> 570 * then the result is positive zero. 571 * 572 * <li>If the absolute value of the first argument equals 1 and the 573 * second argument is infinite, then the result is NaN. 574 * 575 * <li>If 576 * <ul> 577 * <li>the first argument is positive zero and the second argument 578 * is greater than zero, or 579 * <li>the first argument is positive infinity and the second 580 * argument is less than zero, 581 * </ul> 582 * then the result is positive zero. 583 * 584 * <li>If 585 * <ul> 586 * <li>the first argument is positive zero and the second argument 587 * is less than zero, or 588 * <li>the first argument is positive infinity and the second 589 * argument is greater than zero, 590 * </ul> 591 * then the result is positive infinity. 592 * 593 * <li>If 594 * <ul> 595 * <li>the first argument is negative zero and the second argument 596 * is greater than zero but not a finite odd integer, or 597 * <li>the first argument is negative infinity and the second 598 * argument is less than zero but not a finite odd integer, 599 * </ul> 600 * then the result is positive zero. 601 * 602 * <li>If 603 * <ul> 604 * <li>the first argument is negative zero and the second argument 605 * is a positive finite odd integer, or 606 * <li>the first argument is negative infinity and the second 607 * argument is a negative finite odd integer, 608 * </ul> 609 * then the result is negative zero. 610 * 611 * <li>If 612 * <ul> 613 * <li>the first argument is negative zero and the second argument 614 * is less than zero but not a finite odd integer, or 615 * <li>the first argument is negative infinity and the second 616 * argument is greater than zero but not a finite odd integer, 617 * </ul> 618 * then the result is positive infinity. 619 * 620 * <li>If 621 * <ul> 622 * <li>the first argument is negative zero and the second argument 623 * is a negative finite odd integer, or 624 * <li>the first argument is negative infinity and the second 625 * argument is a positive finite odd integer, 626 * </ul> 627 * then the result is negative infinity. 628 * 629 * <li>If the first argument is finite and less than zero 630 * <ul> 631 * <li> if the second argument is a finite even integer, the 632 * result is equal to the result of raising the absolute value of 633 * the first argument to the power of the second argument 634 * 635 * <li>if the second argument is a finite odd integer, the result 636 * is equal to the negative of the result of raising the absolute 637 * value of the first argument to the power of the second 638 * argument 639 * 640 * <li>if the second argument is finite and not an integer, then 641 * the result is NaN. 642 * </ul> 643 * 644 * <li>If both arguments are integers, then the result is exactly equal 645 * to the mathematical result of raising the first argument to the power 646 * of the second argument if that result can in fact be represented 647 * exactly as a {@code double} value.</ul> 648 * 649 * <p>(In the foregoing descriptions, a floating-point value is 650 * considered to be an integer if and only if it is finite and a 651 * fixed point of the method {@link #ceil ceil} or, 652 * equivalently, a fixed point of the method {@link #floor 653 * floor}. A value is a fixed point of a one-argument 654 * method if and only if the result of applying the method to the 655 * value is equal to the value.) 656 * 657 * <p>The computed result must be within 1 ulp of the exact result. 658 * Results must be semi-monotonic. 659 * 660 * @param a the base. 661 * @param b the exponent. 662 * @return the value {@code a}<sup>{@code b}</sup>. 663 */ 664 @HotSpotIntrinsicCandidate 665 public static double pow(double a, double b) { 666 return StrictMath.pow(a, b); // default impl. delegates to StrictMath 667 } 668 669 /** 670 * Returns the closest {@code int} to the argument, with ties 671 * rounding to positive infinity. 672 * 673 * <p> 674 * 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 Integer.MIN_VALUE}, the result is 678 * equal to the value of {@code Integer.MIN_VALUE}. 679 * <li>If the argument is positive infinity or any value greater than or 680 * equal to the value of {@code Integer.MAX_VALUE}, the result is 681 * equal to the value of {@code Integer.MAX_VALUE}.</ul> 682 * 683 * @param a a floating-point value to be rounded to an integer. 684 * @return the value of the argument rounded to the nearest 685 * {@code int} value. 686 * @see java.lang.Integer#MAX_VALUE 687 * @see java.lang.Integer#MIN_VALUE 688 */ 689 public static int round(float a) { 690 int intBits = Float.floatToRawIntBits(a); 691 int biasedExp = (intBits & FloatConsts.EXP_BIT_MASK) 692 >> (FloatConsts.SIGNIFICAND_WIDTH - 1); 693 int shift = (FloatConsts.SIGNIFICAND_WIDTH - 2 694 + FloatConsts.EXP_BIAS) - biasedExp; 695 if ((shift & -32) == 0) { // shift >= 0 && shift < 32 696 // a is a finite number such that pow(2,-32) <= ulp(a) < 1 697 int r = ((intBits & FloatConsts.SIGNIF_BIT_MASK) 698 | (FloatConsts.SIGNIF_BIT_MASK + 1)); 699 if (intBits < 0) { 700 r = -r; 701 } 702 // In the comments below each Java expression evaluates to the value 703 // the corresponding mathematical expression: 704 // (r) evaluates to a / ulp(a) 705 // (r >> shift) evaluates to floor(a * 2) 706 // ((r >> shift) + 1) evaluates to floor((a + 1/2) * 2) 707 // (((r >> shift) + 1) >> 1) evaluates to floor(a + 1/2) 708 return ((r >> shift) + 1) >> 1; 709 } else { 710 // a is either 711 // - a finite number with abs(a) < exp(2,FloatConsts.SIGNIFICAND_WIDTH-32) < 1/2 712 // - a finite number with ulp(a) >= 1 and hence a is a mathematical integer 713 // - an infinity or NaN 714 return (int) a; 715 } 716 } 717 718 /** 719 * Returns the closest {@code long} to the argument, with ties 720 * rounding to positive infinity. 721 * 722 * <p>Special cases: 723 * <ul><li>If the argument is NaN, the result is 0. 724 * <li>If the argument is negative infinity or any value less than or 725 * equal to the value of {@code Long.MIN_VALUE}, the result is 726 * equal to the value of {@code Long.MIN_VALUE}. 727 * <li>If the argument is positive infinity or any value greater than or 728 * equal to the value of {@code Long.MAX_VALUE}, the result is 729 * equal to the value of {@code Long.MAX_VALUE}.</ul> 730 * 731 * @param a a floating-point value to be rounded to a 732 * {@code long}. 733 * @return the value of the argument rounded to the nearest 734 * {@code long} value. 735 * @see java.lang.Long#MAX_VALUE 736 * @see java.lang.Long#MIN_VALUE 737 */ 738 public static long round(double a) { 739 long longBits = Double.doubleToRawLongBits(a); 740 long biasedExp = (longBits & DoubleConsts.EXP_BIT_MASK) 741 >> (DoubleConsts.SIGNIFICAND_WIDTH - 1); 742 long shift = (DoubleConsts.SIGNIFICAND_WIDTH - 2 743 + DoubleConsts.EXP_BIAS) - biasedExp; 744 if ((shift & -64) == 0) { // shift >= 0 && shift < 64 745 // a is a finite number such that pow(2,-64) <= ulp(a) < 1 746 long r = ((longBits & DoubleConsts.SIGNIF_BIT_MASK) 747 | (DoubleConsts.SIGNIF_BIT_MASK + 1)); 748 if (longBits < 0) { 749 r = -r; 750 } 751 // In the comments below each Java expression evaluates to the value 752 // the corresponding mathematical expression: 753 // (r) evaluates to a / ulp(a) 754 // (r >> shift) evaluates to floor(a * 2) 755 // ((r >> shift) + 1) evaluates to floor((a + 1/2) * 2) 756 // (((r >> shift) + 1) >> 1) evaluates to floor(a + 1/2) 757 return ((r >> shift) + 1) >> 1; 758 } else { 759 // a is either 760 // - a finite number with abs(a) < exp(2,DoubleConsts.SIGNIFICAND_WIDTH-64) < 1/2 761 // - a finite number with ulp(a) >= 1 and hence a is a mathematical integer 762 // - an infinity or NaN 763 return (long) a; 764 } 765 } 766 767 private static final class RandomNumberGeneratorHolder { 768 static final Random randomNumberGenerator = new Random(); 769 } 770 771 /** 772 * Returns a {@code double} value with a positive sign, greater 773 * than or equal to {@code 0.0} and less than {@code 1.0}. 774 * Returned values are chosen pseudorandomly with (approximately) 775 * uniform distribution from that range. 776 * 777 * <p>When this method is first called, it creates a single new 778 * pseudorandom-number generator, exactly as if by the expression 779 * 780 * <blockquote>{@code new java.util.Random()}</blockquote> 781 * 782 * This new pseudorandom-number generator is used thereafter for 783 * all calls to this method and is used nowhere else. 784 * 785 * <p>This method is properly synchronized to allow correct use by 786 * more than one thread. However, if many threads need to generate 787 * pseudorandom numbers at a great rate, it may reduce contention 788 * for each thread to have its own pseudorandom-number generator. 789 * 790 * @apiNote 791 * As the largest {@code double} value less than {@code 1.0} 792 * is {@code Math.nextDown(1.0)}, a value {@code x} in the closed range 793 * {@code [x1,x2]} where {@code x1<=x2} may be defined by the statements 794 * 795 * <blockquote><pre>{@code 796 * double f = Math.random()/Math.nextDown(1.0); 797 * double x = x1*(1.0 - f) + x2*f; 798 * }</pre></blockquote> 799 * 800 * @return a pseudorandom {@code double} greater than or equal 801 * to {@code 0.0} and less than {@code 1.0}. 802 * @see #nextDown(double) 803 * @see Random#nextDouble() 804 */ 805 public static double random() { 806 return RandomNumberGeneratorHolder.randomNumberGenerator.nextDouble(); 807 } 808 809 /** 810 * Returns the sum of its arguments, 811 * throwing an exception if the result overflows an {@code int}. 812 * 813 * @param x the first value 814 * @param y the second value 815 * @return the result 816 * @throws ArithmeticException if the result overflows an int 817 * @since 1.8 818 */ 819 @HotSpotIntrinsicCandidate 820 public static int addExact(int x, int y) { 821 int r = x + y; 822 // HD 2-12 Overflow iff both arguments have the opposite sign of the result 823 if (((x ^ r) & (y ^ r)) < 0) { 824 throw new ArithmeticException("integer overflow"); 825 } 826 return r; 827 } 828 829 /** 830 * Returns the sum of its arguments, 831 * throwing an exception if the result overflows a {@code long}. 832 * 833 * @param x the first value 834 * @param y the second value 835 * @return the result 836 * @throws ArithmeticException if the result overflows a long 837 * @since 1.8 838 */ 839 @HotSpotIntrinsicCandidate 840 public static long addExact(long x, long y) { 841 long r = x + y; 842 // HD 2-12 Overflow iff both arguments have the opposite sign of the result 843 if (((x ^ r) & (y ^ r)) < 0) { 844 throw new ArithmeticException("long overflow"); 845 } 846 return r; 847 } 848 849 /** 850 * Returns the difference of the arguments, 851 * throwing an exception if the result overflows an {@code int}. 852 * 853 * @param x the first value 854 * @param y the second value to subtract from the first 855 * @return the result 856 * @throws ArithmeticException if the result overflows an int 857 * @since 1.8 858 */ 859 @HotSpotIntrinsicCandidate 860 public static int subtractExact(int x, int y) { 861 int r = x - y; 862 // HD 2-12 Overflow iff the arguments have different signs and 863 // the sign of the result is different than the sign of x 864 if (((x ^ y) & (x ^ r)) < 0) { 865 throw new ArithmeticException("integer overflow"); 866 } 867 return r; 868 } 869 870 /** 871 * Returns the difference of the arguments, 872 * throwing an exception if the result overflows a {@code long}. 873 * 874 * @param x the first value 875 * @param y the second value to subtract from the first 876 * @return the result 877 * @throws ArithmeticException if the result overflows a long 878 * @since 1.8 879 */ 880 @HotSpotIntrinsicCandidate 881 public static long subtractExact(long x, long y) { 882 long r = x - y; 883 // HD 2-12 Overflow iff the arguments have different signs and 884 // the sign of the result is different than the sign of x 885 if (((x ^ y) & (x ^ r)) < 0) { 886 throw new ArithmeticException("long overflow"); 887 } 888 return r; 889 } 890 891 /** 892 * Returns the product of the arguments, 893 * throwing an exception if the result overflows an {@code int}. 894 * 895 * @param x the first value 896 * @param y the second value 897 * @return the result 898 * @throws ArithmeticException if the result overflows an int 899 * @since 1.8 900 */ 901 @HotSpotIntrinsicCandidate 902 public static int multiplyExact(int x, int y) { 903 long r = (long)x * (long)y; 904 if ((int)r != r) { 905 throw new ArithmeticException("integer overflow"); 906 } 907 return (int)r; 908 } 909 910 /** 911 * Returns the product of the arguments, 912 * throwing an exception if the result overflows a {@code long}. 913 * 914 * @param x the first value 915 * @param y the second value 916 * @return the result 917 * @throws ArithmeticException if the result overflows a long 918 * @since 1.8 919 */ 920 @HotSpotIntrinsicCandidate 921 public static long multiplyExact(long x, long y) { 922 long r = x * y; 923 long ax = Math.abs(x); 924 long ay = Math.abs(y); 925 if (((ax | ay) >>> 31 != 0)) { 926 // Some bits greater than 2^31 that might cause overflow 927 // Check the result using the divide operator 928 // and check for the special case of Long.MIN_VALUE * -1 929 if (((y != 0) && (r / y != x)) || 930 (x == Long.MIN_VALUE && y == -1)) { 931 throw new ArithmeticException("long overflow"); 932 } 933 } 934 return r; 935 } 936 937 /** 938 * Returns the argument incremented by one, throwing an exception if the 939 * result overflows an {@code int}. 940 * 941 * @param a the value to increment 942 * @return the result 943 * @throws ArithmeticException if the result overflows an int 944 * @since 1.8 945 */ 946 @HotSpotIntrinsicCandidate 947 public static int incrementExact(int a) { 948 if (a == Integer.MAX_VALUE) { 949 throw new ArithmeticException("integer overflow"); 950 } 951 952 return a + 1; 953 } 954 955 /** 956 * Returns the argument incremented by one, throwing an exception if the 957 * result overflows a {@code long}. 958 * 959 * @param a the value to increment 960 * @return the result 961 * @throws ArithmeticException if the result overflows a long 962 * @since 1.8 963 */ 964 @HotSpotIntrinsicCandidate 965 public static long incrementExact(long a) { 966 if (a == Long.MAX_VALUE) { 967 throw new ArithmeticException("long overflow"); 968 } 969 970 return a + 1L; 971 } 972 973 /** 974 * Returns the argument decremented by one, throwing an exception if the 975 * result overflows an {@code int}. 976 * 977 * @param a the value to decrement 978 * @return the result 979 * @throws ArithmeticException if the result overflows an int 980 * @since 1.8 981 */ 982 @HotSpotIntrinsicCandidate 983 public static int decrementExact(int a) { 984 if (a == Integer.MIN_VALUE) { 985 throw new ArithmeticException("integer overflow"); 986 } 987 988 return a - 1; 989 } 990 991 /** 992 * Returns the argument decremented by one, throwing an exception if the 993 * result overflows a {@code long}. 994 * 995 * @param a the value to decrement 996 * @return the result 997 * @throws ArithmeticException if the result overflows a long 998 * @since 1.8 999 */ 1000 @HotSpotIntrinsicCandidate 1001 public static long decrementExact(long a) { 1002 if (a == Long.MIN_VALUE) { 1003 throw new ArithmeticException("long overflow"); 1004 } 1005 1006 return a - 1L; 1007 } 1008 1009 /** 1010 * Returns the negation of the argument, throwing an exception if the 1011 * result overflows an {@code int}. 1012 * 1013 * @param a the value to negate 1014 * @return the result 1015 * @throws ArithmeticException if the result overflows an int 1016 * @since 1.8 1017 */ 1018 @HotSpotIntrinsicCandidate 1019 public static int negateExact(int a) { 1020 if (a == Integer.MIN_VALUE) { 1021 throw new ArithmeticException("integer overflow"); 1022 } 1023 1024 return -a; 1025 } 1026 1027 /** 1028 * Returns the negation of the argument, throwing an exception if the 1029 * result overflows a {@code long}. 1030 * 1031 * @param a the value to negate 1032 * @return the result 1033 * @throws ArithmeticException if the result overflows a long 1034 * @since 1.8 1035 */ 1036 @HotSpotIntrinsicCandidate 1037 public static long negateExact(long a) { 1038 if (a == Long.MIN_VALUE) { 1039 throw new ArithmeticException("long overflow"); 1040 } 1041 1042 return -a; 1043 } 1044 1045 /** 1046 * Returns the value of the {@code long} argument; 1047 * throwing an exception if the value overflows an {@code int}. 1048 * 1049 * @param value the long value 1050 * @return the argument as an int 1051 * @throws ArithmeticException if the {@code argument} overflows an int 1052 * @since 1.8 1053 */ 1054 public static int toIntExact(long value) { 1055 if ((int)value != value) { 1056 throw new ArithmeticException("integer overflow"); 1057 } 1058 return (int)value; 1059 } 1060 1061 /** 1062 * Returns the largest (closest to positive infinity) 1063 * {@code int} value that is less than or equal to the algebraic quotient. 1064 * There is one special case, if the dividend is the 1065 * {@linkplain Integer#MIN_VALUE Integer.MIN_VALUE} and the divisor is {@code -1}, 1066 * then integer overflow occurs and 1067 * the result is equal to the {@code Integer.MIN_VALUE}. 1068 * <p> 1069 * Normal integer division operates under the round to zero rounding mode 1070 * (truncation). This operation instead acts under the round toward 1071 * negative infinity (floor) rounding mode. 1072 * The floor rounding mode gives different results than truncation 1073 * when the exact result is negative. 1074 * <ul> 1075 * <li>If the signs of the arguments are the same, the results of 1076 * {@code floorDiv} and the {@code /} operator are the same. <br> 1077 * For example, {@code floorDiv(4, 3) == 1} and {@code (4 / 3) == 1}.</li> 1078 * <li>If the signs of the arguments are different, the quotient is negative and 1079 * {@code floorDiv} returns the integer less than or equal to the quotient 1080 * and the {@code /} operator returns the integer closest to zero.<br> 1081 * For example, {@code floorDiv(-4, 3) == -2}, 1082 * whereas {@code (-4 / 3) == -1}. 1083 * </li> 1084 * </ul> 1085 * 1086 * @param x the dividend 1087 * @param y the divisor 1088 * @return the largest (closest to positive infinity) 1089 * {@code int} value that is less than or equal to the algebraic quotient. 1090 * @throws ArithmeticException if the divisor {@code y} is zero 1091 * @see #floorMod(int, int) 1092 * @see #floor(double) 1093 * @since 1.8 1094 */ 1095 public static int floorDiv(int x, int y) { 1096 int r = x / y; 1097 // if the signs are different and modulo not zero, round down 1098 if ((x ^ y) < 0 && (r * y != x)) { 1099 r--; 1100 } 1101 return r; 1102 } 1103 1104 /** 1105 * Returns the largest (closest to positive infinity) 1106 * {@code long} value that is less than or equal to the algebraic quotient. 1107 * There is one special case, if the dividend is the 1108 * {@linkplain Long#MIN_VALUE Long.MIN_VALUE} and the divisor is {@code -1}, 1109 * then integer overflow occurs and 1110 * the result is equal to the {@code Long.MIN_VALUE}. 1111 * <p> 1112 * Normal integer division operates under the round to zero rounding mode 1113 * (truncation). This operation instead acts under the round toward 1114 * negative infinity (floor) rounding mode. 1115 * The floor rounding mode gives different results than truncation 1116 * when the exact result is negative. 1117 * <p> 1118 * For examples, see {@link #floorDiv(int, int)}. 1119 * 1120 * @param x the dividend 1121 * @param y the divisor 1122 * @return the largest (closest to positive infinity) 1123 * {@code long} value that is less than or equal to the algebraic quotient. 1124 * @throws ArithmeticException if the divisor {@code y} is zero 1125 * @see #floorMod(long, long) 1126 * @see #floor(double) 1127 * @since 1.8 1128 */ 1129 public static long floorDiv(long x, long y) { 1130 long r = x / y; 1131 // if the signs are different and modulo not zero, round down 1132 if ((x ^ y) < 0 && (r * y != x)) { 1133 r--; 1134 } 1135 return r; 1136 } 1137 1138 /** 1139 * Returns the floor modulus of the {@code int} 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 * 1145 * <p> 1146 * The relationship between {@code floorDiv} and {@code floorMod} is such that: 1147 * <ul> 1148 * <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x} 1149 * </ul> 1150 * <p> 1151 * The difference in values between {@code floorMod} and 1152 * the {@code %} operator is due to the difference between 1153 * {@code floorDiv} that returns the integer less than or equal to the quotient 1154 * and the {@code /} operator that returns the integer closest to zero. 1155 * <p> 1156 * Examples: 1157 * <ul> 1158 * <li>If the signs of the arguments are the same, the results 1159 * of {@code floorMod} and the {@code %} operator are the same. <br> 1160 * <ul> 1161 * <li>{@code floorMod(4, 3) == 1}; and {@code (4 % 3) == 1}</li> 1162 * </ul> 1163 * <li>If the signs of the arguments are different, the results differ from the {@code %} operator.<br> 1164 * <ul> 1165 * <li>{@code floorMod(+4, -3) == -2}; and {@code (+4 % -3) == +1} </li> 1166 * <li>{@code floorMod(-4, +3) == +2}; and {@code (-4 % +3) == -1} </li> 1167 * <li>{@code floorMod(-4, -3) == -1}; and {@code (-4 % -3) == -1 } </li> 1168 * </ul> 1169 * </li> 1170 * </ul> 1171 * <p> 1172 * If the signs of arguments are unknown and a positive modulus 1173 * is needed it can be computed as {@code (floorMod(x, y) + abs(y)) % abs(y)}. 1174 * 1175 * @param x the dividend 1176 * @param y the divisor 1177 * @return the floor modulus {@code x - (floorDiv(x, y) * y)} 1178 * @throws ArithmeticException if the divisor {@code y} is zero 1179 * @see #floorDiv(int, int) 1180 * @since 1.8 1181 */ 1182 public static int floorMod(int x, int y) { 1183 int r = x - floorDiv(x, y) * y; 1184 return r; 1185 } 1186 1187 /** 1188 * Returns the floor modulus of the {@code long} arguments. 1189 * <p> 1190 * The floor modulus is {@code x - (floorDiv(x, y) * y)}, 1191 * has the same sign as the divisor {@code y}, and 1192 * is in the range of {@code -abs(y) < r < +abs(y)}. 1193 * 1194 * <p> 1195 * The relationship between {@code floorDiv} and {@code floorMod} is such that: 1196 * <ul> 1197 * <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x} 1198 * </ul> 1199 * <p> 1200 * For examples, see {@link #floorMod(int, int)}. 1201 * 1202 * @param x the dividend 1203 * @param y the divisor 1204 * @return the floor modulus {@code x - (floorDiv(x, y) * y)} 1205 * @throws ArithmeticException if the divisor {@code y} is zero 1206 * @see #floorDiv(long, long) 1207 * @since 1.8 1208 */ 1209 public static long floorMod(long x, long y) { 1210 return x - floorDiv(x, y) * y; 1211 } 1212 1213 /** 1214 * Returns the absolute value of an {@code int} value. 1215 * If the argument is not negative, the argument is returned. 1216 * If the argument is negative, the negation of the argument is returned. 1217 * 1218 * <p>Note that if the argument is equal to the value of 1219 * {@link Integer#MIN_VALUE}, the most negative representable 1220 * {@code int} value, the result is that same value, which is 1221 * negative. 1222 * 1223 * @param a the argument whose absolute value is to be determined 1224 * @return the absolute value of the argument. 1225 */ 1226 public static int abs(int a) { 1227 return (a < 0) ? -a : a; 1228 } 1229 1230 /** 1231 * Returns the absolute value of a {@code long} value. 1232 * If the argument is not negative, the argument is returned. 1233 * If the argument is negative, the negation of the argument is returned. 1234 * 1235 * <p>Note that if the argument is equal to the value of 1236 * {@link Long#MIN_VALUE}, the most negative representable 1237 * {@code long} value, the result is that same value, which 1238 * is negative. 1239 * 1240 * @param a the argument whose absolute value is to be determined 1241 * @return the absolute value of the argument. 1242 */ 1243 public static long abs(long a) { 1244 return (a < 0) ? -a : a; 1245 } 1246 1247 /** 1248 * Returns the absolute value of a {@code float} value. 1249 * If the argument is not negative, the argument is returned. 1250 * If the argument is negative, the negation of the argument is returned. 1251 * Special cases: 1252 * <ul><li>If the argument is positive zero or negative zero, the 1253 * result is positive zero. 1254 * <li>If the argument is infinite, the result is positive infinity. 1255 * <li>If the argument is NaN, the result is NaN.</ul> 1256 * In other words, the result is the same as the value of the expression: 1257 * <p>{@code Float.intBitsToFloat(0x7fffffff & Float.floatToIntBits(a))} 1258 * 1259 * @param a the argument whose absolute value is to be determined 1260 * @return the absolute value of the argument. 1261 */ 1262 public static float abs(float a) { 1263 return (a <= 0.0F) ? 0.0F - a : a; 1264 } 1265 1266 /** 1267 * Returns the absolute value of a {@code double} value. 1268 * If the argument is not negative, the argument is returned. 1269 * If the argument is negative, the negation of the argument is returned. 1270 * Special cases: 1271 * <ul><li>If the argument is positive zero or negative zero, the result 1272 * is positive zero. 1273 * <li>If the argument is infinite, the result is positive infinity. 1274 * <li>If the argument is NaN, the result is NaN.</ul> 1275 * In other words, the result is the same as the value of the expression: 1276 * <p>{@code Double.longBitsToDouble((Double.doubleToLongBits(a)<<1)>>>1)} 1277 * 1278 * @param a the argument whose absolute value is to be determined 1279 * @return the absolute value of the argument. 1280 */ 1281 @HotSpotIntrinsicCandidate 1282 public static double abs(double a) { 1283 return (a <= 0.0D) ? 0.0D - a : a; 1284 } 1285 1286 /** 1287 * Returns the greater of two {@code int} values. That is, the 1288 * result is the argument closer to the value of 1289 * {@link Integer#MAX_VALUE}. If the arguments have the same value, 1290 * the result is that same value. 1291 * 1292 * @param a an argument. 1293 * @param b another argument. 1294 * @return the larger of {@code a} and {@code b}. 1295 */ 1296 @HotSpotIntrinsicCandidate 1297 public static int max(int a, int b) { 1298 return (a >= b) ? a : b; 1299 } 1300 1301 /** 1302 * Returns the greater of two {@code long} values. That is, the 1303 * result is the argument closer to the value of 1304 * {@link Long#MAX_VALUE}. If the arguments have the same value, 1305 * the result is that same value. 1306 * 1307 * @param a an argument. 1308 * @param b another argument. 1309 * @return the larger of {@code a} and {@code b}. 1310 */ 1311 public static long max(long a, long b) { 1312 return (a >= b) ? a : b; 1313 } 1314 1315 // Use raw bit-wise conversions on guaranteed non-NaN arguments. 1316 private static long negativeZeroFloatBits = Float.floatToRawIntBits(-0.0f); 1317 private static long negativeZeroDoubleBits = Double.doubleToRawLongBits(-0.0d); 1318 1319 /** 1320 * Returns the greater of two {@code float} values. That is, 1321 * the result is the argument closer to positive infinity. If the 1322 * arguments have the same value, the result is that same 1323 * value. If either value is NaN, then the result is NaN. Unlike 1324 * the numerical comparison operators, this method considers 1325 * negative zero to be strictly smaller than positive zero. If one 1326 * argument is positive zero and the other negative zero, the 1327 * result is positive zero. 1328 * 1329 * @param a an argument. 1330 * @param b another argument. 1331 * @return the larger of {@code a} and {@code b}. 1332 */ 1333 public static float max(float a, float b) { 1334 if (a != a) 1335 return a; // a is NaN 1336 if ((a == 0.0f) && 1337 (b == 0.0f) && 1338 (Float.floatToRawIntBits(a) == negativeZeroFloatBits)) { 1339 // Raw conversion ok since NaN can't map to -0.0. 1340 return b; 1341 } 1342 return (a >= b) ? 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 public static double max(double a, double b) { 1360 if (a != a) 1361 return a; // a is NaN 1362 if ((a == 0.0d) && 1363 (b == 0.0d) && 1364 (Double.doubleToRawLongBits(a) == negativeZeroDoubleBits)) { 1365 // Raw conversion ok since NaN can't map to -0.0. 1366 return b; 1367 } 1368 return (a >= b) ? a : b; 1369 } 1370 1371 /** 1372 * Returns the smaller of two {@code int} values. That is, 1373 * the result the argument closer to the value of 1374 * {@link Integer#MIN_VALUE}. If the arguments have the same 1375 * value, the result is that same value. 1376 * 1377 * @param a an argument. 1378 * @param b another argument. 1379 * @return the smaller of {@code a} and {@code b}. 1380 */ 1381 @HotSpotIntrinsicCandidate 1382 public static int min(int a, int b) { 1383 return (a <= b) ? a : b; 1384 } 1385 1386 /** 1387 * Returns the smaller of two {@code long} values. That is, 1388 * the result is the argument closer to the value of 1389 * {@link Long#MIN_VALUE}. If the arguments have the same 1390 * value, the result is that same value. 1391 * 1392 * @param a an argument. 1393 * @param b another argument. 1394 * @return the smaller of {@code a} and {@code b}. 1395 */ 1396 public static long min(long a, long b) { 1397 return (a <= b) ? a : b; 1398 } 1399 1400 /** 1401 * Returns the smaller of two {@code float} values. That is, 1402 * the result is the value closer to negative infinity. If the 1403 * arguments have the same value, the result is that same 1404 * value. If either value is NaN, then the result is NaN. Unlike 1405 * the numerical comparison operators, this method considers 1406 * negative zero to be strictly smaller than positive zero. If 1407 * one argument is positive zero and the other is negative zero, 1408 * the result is negative zero. 1409 * 1410 * @param a an argument. 1411 * @param b another argument. 1412 * @return the smaller of {@code a} and {@code b}. 1413 */ 1414 public static float min(float a, float b) { 1415 if (a != a) 1416 return a; // a is NaN 1417 if ((a == 0.0f) && 1418 (b == 0.0f) && 1419 (Float.floatToRawIntBits(b) == negativeZeroFloatBits)) { 1420 // Raw conversion ok since NaN can't map to -0.0. 1421 return b; 1422 } 1423 return (a <= b) ? a : b; 1424 } 1425 1426 /** 1427 * Returns the smaller of two {@code double} values. That 1428 * is, the result is the value closer to negative infinity. If the 1429 * arguments have the same value, the result is that same 1430 * value. If either value is NaN, then the result is NaN. Unlike 1431 * the numerical comparison operators, this method considers 1432 * negative zero to be strictly smaller than positive zero. If one 1433 * argument is positive zero and the other is negative zero, the 1434 * result is negative zero. 1435 * 1436 * @param a an argument. 1437 * @param b another argument. 1438 * @return the smaller of {@code a} and {@code b}. 1439 */ 1440 public static double min(double a, double b) { 1441 if (a != a) 1442 return a; // a is NaN 1443 if ((a == 0.0d) && 1444 (b == 0.0d) && 1445 (Double.doubleToRawLongBits(b) == negativeZeroDoubleBits)) { 1446 // Raw conversion ok since NaN can't map to -0.0. 1447 return b; 1448 } 1449 return (a <= b) ? a : b; 1450 } 1451 1452 /** 1453 * Returns the size of an ulp of the argument. An ulp, unit in 1454 * the last place, of a {@code double} value is the positive 1455 * distance between this floating-point value and the {@code 1456 * double} value next larger in magnitude. Note that for non-NaN 1457 * <i>x</i>, <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>. 1458 * 1459 * <p>Special Cases: 1460 * <ul> 1461 * <li> If the argument is NaN, then the result is NaN. 1462 * <li> If the argument is positive or negative infinity, then the 1463 * result is positive infinity. 1464 * <li> If the argument is positive or negative zero, then the result is 1465 * {@code Double.MIN_VALUE}. 1466 * <li> If the argument is ±{@code Double.MAX_VALUE}, then 1467 * the result is equal to 2<sup>971</sup>. 1468 * </ul> 1469 * 1470 * @param d the floating-point value whose ulp is to be returned 1471 * @return the size of an ulp of the argument 1472 * @author Joseph D. Darcy 1473 * @since 1.5 1474 */ 1475 public static double ulp(double d) { 1476 int exp = getExponent(d); 1477 1478 switch(exp) { 1479 case DoubleConsts.MAX_EXPONENT+1: // NaN or infinity 1480 return Math.abs(d); 1481 1482 case DoubleConsts.MIN_EXPONENT-1: // zero or subnormal 1483 return Double.MIN_VALUE; 1484 1485 default: 1486 assert exp <= DoubleConsts.MAX_EXPONENT && exp >= DoubleConsts.MIN_EXPONENT; 1487 1488 // ulp(x) is usually 2^(SIGNIFICAND_WIDTH-1)*(2^ilogb(x)) 1489 exp = exp - (DoubleConsts.SIGNIFICAND_WIDTH-1); 1490 if (exp >= DoubleConsts.MIN_EXPONENT) { 1491 return powerOfTwoD(exp); 1492 } 1493 else { 1494 // return a subnormal result; left shift integer 1495 // representation of Double.MIN_VALUE appropriate 1496 // number of positions 1497 return Double.longBitsToDouble(1L << 1498 (exp - (DoubleConsts.MIN_EXPONENT - (DoubleConsts.SIGNIFICAND_WIDTH-1)) )); 1499 } 1500 } 1501 } 1502 1503 /** 1504 * Returns the size of an ulp of the argument. An ulp, unit in 1505 * the last place, of a {@code float} value is the positive 1506 * distance between this floating-point value and the {@code 1507 * float} value next larger in magnitude. Note that for non-NaN 1508 * <i>x</i>, <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>. 1509 * 1510 * <p>Special Cases: 1511 * <ul> 1512 * <li> If the argument is NaN, then the result is NaN. 1513 * <li> If the argument is positive or negative infinity, then the 1514 * result is positive infinity. 1515 * <li> If the argument is positive or negative zero, then the result is 1516 * {@code Float.MIN_VALUE}. 1517 * <li> If the argument is ±{@code Float.MAX_VALUE}, then 1518 * the result is equal to 2<sup>104</sup>. 1519 * </ul> 1520 * 1521 * @param f the floating-point value whose ulp is to be returned 1522 * @return the size of an ulp of the argument 1523 * @author Joseph D. Darcy 1524 * @since 1.5 1525 */ 1526 public static float ulp(float f) { 1527 int exp = getExponent(f); 1528 1529 switch(exp) { 1530 case FloatConsts.MAX_EXPONENT+1: // NaN or infinity 1531 return Math.abs(f); 1532 1533 case FloatConsts.MIN_EXPONENT-1: // zero or subnormal 1534 return FloatConsts.MIN_VALUE; 1535 1536 default: 1537 assert exp <= FloatConsts.MAX_EXPONENT && exp >= FloatConsts.MIN_EXPONENT; 1538 1539 // ulp(x) is usually 2^(SIGNIFICAND_WIDTH-1)*(2^ilogb(x)) 1540 exp = exp - (FloatConsts.SIGNIFICAND_WIDTH-1); 1541 if (exp >= FloatConsts.MIN_EXPONENT) { 1542 return powerOfTwoF(exp); 1543 } 1544 else { 1545 // return a subnormal result; left shift integer 1546 // representation of FloatConsts.MIN_VALUE appropriate 1547 // number of positions 1548 return Float.intBitsToFloat(1 << 1549 (exp - (FloatConsts.MIN_EXPONENT - (FloatConsts.SIGNIFICAND_WIDTH-1)) )); 1550 } 1551 } 1552 } 1553 1554 /** 1555 * Returns the signum function of the argument; zero if the argument 1556 * is zero, 1.0 if the argument is greater than zero, -1.0 if the 1557 * argument is less than zero. 1558 * 1559 * <p>Special Cases: 1560 * <ul> 1561 * <li> If the argument is NaN, then the result is NaN. 1562 * <li> If the argument is positive zero or negative zero, then the 1563 * result is the same as the argument. 1564 * </ul> 1565 * 1566 * @param d the floating-point value whose signum is to be returned 1567 * @return the signum function of the argument 1568 * @author Joseph D. Darcy 1569 * @since 1.5 1570 */ 1571 public static double signum(double d) { 1572 return (d == 0.0 || Double.isNaN(d))?d:copySign(1.0, d); 1573 } 1574 1575 /** 1576 * Returns the signum function of the argument; zero if the argument 1577 * is zero, 1.0f if the argument is greater than zero, -1.0f if the 1578 * argument is less than zero. 1579 * 1580 * <p>Special Cases: 1581 * <ul> 1582 * <li> If the argument is NaN, then the result is NaN. 1583 * <li> If the argument is positive zero or negative zero, then the 1584 * result is the same as the argument. 1585 * </ul> 1586 * 1587 * @param f the floating-point value whose signum is to be returned 1588 * @return the signum function of the argument 1589 * @author Joseph D. Darcy 1590 * @since 1.5 1591 */ 1592 public static float signum(float f) { 1593 return (f == 0.0f || Float.isNaN(f))?f:copySign(1.0f, f); 1594 } 1595 1596 /** 1597 * Returns the hyperbolic sine of a {@code double} value. 1598 * The hyperbolic sine of <i>x</i> is defined to be 1599 * (<i>e<sup>x</sup> - e<sup>-x</sup></i>)/2 1600 * where <i>e</i> is {@linkplain Math#E Euler's number}. 1601 * 1602 * <p>Special cases: 1603 * <ul> 1604 * 1605 * <li>If the argument is NaN, then the result is NaN. 1606 * 1607 * <li>If the argument is infinite, then the result is an infinity 1608 * with the same sign as the argument. 1609 * 1610 * <li>If the argument is zero, then the result is a zero with the 1611 * same sign as the argument. 1612 * 1613 * </ul> 1614 * 1615 * <p>The computed result must be within 2.5 ulps of the exact result. 1616 * 1617 * @param x The number whose hyperbolic sine is to be returned. 1618 * @return The hyperbolic sine of {@code x}. 1619 * @since 1.5 1620 */ 1621 public static double sinh(double x) { 1622 return StrictMath.sinh(x); 1623 } 1624 1625 /** 1626 * Returns the hyperbolic cosine of a {@code double} value. 1627 * The hyperbolic cosine of <i>x</i> is defined to be 1628 * (<i>e<sup>x</sup> + e<sup>-x</sup></i>)/2 1629 * where <i>e</i> is {@linkplain Math#E Euler's number}. 1630 * 1631 * <p>Special cases: 1632 * <ul> 1633 * 1634 * <li>If the argument is NaN, then the result is NaN. 1635 * 1636 * <li>If the argument is infinite, then the result is positive 1637 * infinity. 1638 * 1639 * <li>If the argument is zero, then the result is {@code 1.0}. 1640 * 1641 * </ul> 1642 * 1643 * <p>The computed result must be within 2.5 ulps of the exact result. 1644 * 1645 * @param x The number whose hyperbolic cosine is to be returned. 1646 * @return The hyperbolic cosine of {@code x}. 1647 * @since 1.5 1648 */ 1649 public static double cosh(double x) { 1650 return StrictMath.cosh(x); 1651 } 1652 1653 /** 1654 * Returns the hyperbolic tangent of a {@code double} value. 1655 * The hyperbolic tangent of <i>x</i> is defined to be 1656 * (<i>e<sup>x</sup> - e<sup>-x</sup></i>)/(<i>e<sup>x</sup> + e<sup>-x</sup></i>), 1657 * in other words, {@linkplain Math#sinh 1658 * sinh(<i>x</i>)}/{@linkplain Math#cosh cosh(<i>x</i>)}. Note 1659 * that the absolute value of the exact tanh is always less than 1660 * 1. 1661 * 1662 * <p>Special cases: 1663 * <ul> 1664 * 1665 * <li>If the argument is NaN, then the result is NaN. 1666 * 1667 * <li>If the argument is zero, then the result is a zero with the 1668 * same sign as the argument. 1669 * 1670 * <li>If the argument is positive infinity, then the result is 1671 * {@code +1.0}. 1672 * 1673 * <li>If the argument is negative infinity, then the result is 1674 * {@code -1.0}. 1675 * 1676 * </ul> 1677 * 1678 * <p>The computed result must be within 2.5 ulps of the exact result. 1679 * The result of {@code tanh} for any finite input must have 1680 * an absolute value less than or equal to 1. Note that once the 1681 * exact result of tanh is within 1/2 of an ulp of the limit value 1682 * of ±1, correctly signed ±{@code 1.0} should 1683 * be returned. 1684 * 1685 * @param x The number whose hyperbolic tangent is to be returned. 1686 * @return The hyperbolic tangent of {@code x}. 1687 * @since 1.5 1688 */ 1689 public static double tanh(double x) { 1690 return StrictMath.tanh(x); 1691 } 1692 1693 /** 1694 * Returns sqrt(<i>x</i><sup>2</sup> +<i>y</i><sup>2</sup>) 1695 * without intermediate overflow or underflow. 1696 * 1697 * <p>Special cases: 1698 * <ul> 1699 * 1700 * <li> If either argument is infinite, then the result 1701 * is positive infinity. 1702 * 1703 * <li> If either argument is NaN and neither argument is infinite, 1704 * then the result is NaN. 1705 * 1706 * </ul> 1707 * 1708 * <p>The computed result must be within 1 ulp of the exact 1709 * result. If one parameter is held constant, the results must be 1710 * semi-monotonic in the other parameter. 1711 * 1712 * @param x a value 1713 * @param y a value 1714 * @return sqrt(<i>x</i><sup>2</sup> +<i>y</i><sup>2</sup>) 1715 * without intermediate overflow or underflow 1716 * @since 1.5 1717 */ 1718 public static double hypot(double x, double y) { 1719 return StrictMath.hypot(x, y); 1720 } 1721 1722 /** 1723 * Returns <i>e</i><sup>x</sup> -1. Note that for values of 1724 * <i>x</i> near 0, the exact sum of 1725 * {@code expm1(x)} + 1 is much closer to the true 1726 * result of <i>e</i><sup>x</sup> than {@code exp(x)}. 1727 * 1728 * <p>Special cases: 1729 * <ul> 1730 * <li>If the argument is NaN, the result is NaN. 1731 * 1732 * <li>If the argument is positive infinity, then the result is 1733 * positive infinity. 1734 * 1735 * <li>If the argument is negative infinity, then the result is 1736 * -1.0. 1737 * 1738 * <li>If the argument is zero, then the result is a zero with the 1739 * same sign as the argument. 1740 * 1741 * </ul> 1742 * 1743 * <p>The computed result must be within 1 ulp of the exact result. 1744 * Results must be semi-monotonic. The result of 1745 * {@code expm1} for any finite input must be greater than or 1746 * equal to {@code -1.0}. Note that once the exact result of 1747 * <i>e</i><sup>{@code x}</sup> - 1 is within 1/2 1748 * ulp of the limit value -1, {@code -1.0} should be 1749 * returned. 1750 * 1751 * @param x the exponent to raise <i>e</i> to in the computation of 1752 * <i>e</i><sup>{@code x}</sup> -1. 1753 * @return the value <i>e</i><sup>{@code x}</sup> - 1. 1754 * @since 1.5 1755 */ 1756 public static double expm1(double x) { 1757 return StrictMath.expm1(x); 1758 } 1759 1760 /** 1761 * Returns the natural logarithm of the sum of the argument and 1. 1762 * Note that for small values {@code x}, the result of 1763 * {@code log1p(x)} is much closer to the true result of ln(1 1764 * + {@code x}) than the floating-point evaluation of 1765 * {@code log(1.0+x)}. 1766 * 1767 * <p>Special cases: 1768 * 1769 * <ul> 1770 * 1771 * <li>If the argument is NaN or less than -1, then the result is 1772 * NaN. 1773 * 1774 * <li>If the argument is positive infinity, then the result is 1775 * positive infinity. 1776 * 1777 * <li>If the argument is negative one, then the result is 1778 * negative infinity. 1779 * 1780 * <li>If the argument is zero, then the result is a zero with the 1781 * same sign as the argument. 1782 * 1783 * </ul> 1784 * 1785 * <p>The computed result must be within 1 ulp of the exact result. 1786 * Results must be semi-monotonic. 1787 * 1788 * @param x a value 1789 * @return the value ln({@code x} + 1), the natural 1790 * log of {@code x} + 1 1791 * @since 1.5 1792 */ 1793 public static double log1p(double x) { 1794 return StrictMath.log1p(x); 1795 } 1796 1797 /** 1798 * Returns the first floating-point argument with the sign of the 1799 * second floating-point argument. Note that unlike the {@link 1800 * StrictMath#copySign(double, double) StrictMath.copySign} 1801 * method, this method does not require NaN {@code sign} 1802 * arguments to be treated as positive values; implementations are 1803 * permitted to treat some NaN arguments as positive and other NaN 1804 * arguments as negative to allow greater performance. 1805 * 1806 * @param magnitude the parameter providing the magnitude of the result 1807 * @param sign the parameter providing the sign of the result 1808 * @return a value with the magnitude of {@code magnitude} 1809 * and the sign of {@code sign}. 1810 * @since 1.6 1811 */ 1812 public static double copySign(double magnitude, double sign) { 1813 return Double.longBitsToDouble((Double.doubleToRawLongBits(sign) & 1814 (DoubleConsts.SIGN_BIT_MASK)) | 1815 (Double.doubleToRawLongBits(magnitude) & 1816 (DoubleConsts.EXP_BIT_MASK | 1817 DoubleConsts.SIGNIF_BIT_MASK))); 1818 } 1819 1820 /** 1821 * Returns the first floating-point argument with the sign of the 1822 * second floating-point argument. Note that unlike the {@link 1823 * StrictMath#copySign(float, float) StrictMath.copySign} 1824 * method, this method does not require NaN {@code sign} 1825 * arguments to be treated as positive values; implementations are 1826 * permitted to treat some NaN arguments as positive and other NaN 1827 * arguments as negative to allow greater performance. 1828 * 1829 * @param magnitude the parameter providing the magnitude of the result 1830 * @param sign the parameter providing the sign of the result 1831 * @return a value with the magnitude of {@code magnitude} 1832 * and the sign of {@code sign}. 1833 * @since 1.6 1834 */ 1835 public static float copySign(float magnitude, float sign) { 1836 return Float.intBitsToFloat((Float.floatToRawIntBits(sign) & 1837 (FloatConsts.SIGN_BIT_MASK)) | 1838 (Float.floatToRawIntBits(magnitude) & 1839 (FloatConsts.EXP_BIT_MASK | 1840 FloatConsts.SIGNIF_BIT_MASK))); 1841 } 1842 1843 /** 1844 * Returns the unbiased exponent used in the representation of a 1845 * {@code float}. Special cases: 1846 * 1847 * <ul> 1848 * <li>If the argument is NaN or infinite, then the result is 1849 * {@link Float#MAX_EXPONENT} + 1. 1850 * <li>If the argument is zero or subnormal, then the result is 1851 * {@link Float#MIN_EXPONENT} -1. 1852 * </ul> 1853 * @param f a {@code float} value 1854 * @return the unbiased exponent of the argument 1855 * @since 1.6 1856 */ 1857 public static int getExponent(float f) { 1858 /* 1859 * Bitwise convert f to integer, mask out exponent bits, shift 1860 * to the right and then subtract out float's bias adjust to 1861 * get true exponent value 1862 */ 1863 return ((Float.floatToRawIntBits(f) & FloatConsts.EXP_BIT_MASK) >> 1864 (FloatConsts.SIGNIFICAND_WIDTH - 1)) - FloatConsts.EXP_BIAS; 1865 } 1866 1867 /** 1868 * Returns the unbiased exponent used in the representation of a 1869 * {@code double}. Special cases: 1870 * 1871 * <ul> 1872 * <li>If the argument is NaN or infinite, then the result is 1873 * {@link Double#MAX_EXPONENT} + 1. 1874 * <li>If the argument is zero or subnormal, then the result is 1875 * {@link Double#MIN_EXPONENT} -1. 1876 * </ul> 1877 * @param d a {@code double} value 1878 * @return the unbiased exponent of the argument 1879 * @since 1.6 1880 */ 1881 public static int getExponent(double d) { 1882 /* 1883 * Bitwise convert d to long, mask out exponent bits, shift 1884 * to the right and then subtract out double's bias adjust to 1885 * get true exponent value. 1886 */ 1887 return (int)(((Double.doubleToRawLongBits(d) & DoubleConsts.EXP_BIT_MASK) >> 1888 (DoubleConsts.SIGNIFICAND_WIDTH - 1)) - DoubleConsts.EXP_BIAS); 1889 } 1890 1891 /** 1892 * Returns the floating-point number adjacent to the first 1893 * argument in the direction of the second argument. If both 1894 * arguments compare as equal the second argument is returned. 1895 * 1896 * <p> 1897 * Special cases: 1898 * <ul> 1899 * <li> If either argument is a NaN, then NaN is returned. 1900 * 1901 * <li> If both arguments are signed zeros, {@code direction} 1902 * is returned unchanged (as implied by the requirement of 1903 * returning the second argument if the arguments compare as 1904 * equal). 1905 * 1906 * <li> If {@code start} is 1907 * ±{@link Double#MIN_VALUE} and {@code direction} 1908 * has a value such that the result should have a smaller 1909 * magnitude, then a zero with the same sign as {@code start} 1910 * is returned. 1911 * 1912 * <li> If {@code start} is infinite and 1913 * {@code direction} has a value such that the result should 1914 * have a smaller magnitude, {@link Double#MAX_VALUE} with the 1915 * same sign as {@code start} is returned. 1916 * 1917 * <li> If {@code start} is equal to ± 1918 * {@link Double#MAX_VALUE} and {@code direction} has a 1919 * value such that the result should have a larger magnitude, an 1920 * infinity with same sign as {@code start} is returned. 1921 * </ul> 1922 * 1923 * @param start starting floating-point value 1924 * @param direction value indicating which of 1925 * {@code start}'s neighbors or {@code start} should 1926 * be returned 1927 * @return The floating-point number adjacent to {@code start} in the 1928 * direction of {@code direction}. 1929 * @since 1.6 1930 */ 1931 public static double nextAfter(double start, double direction) { 1932 /* 1933 * The cases: 1934 * 1935 * nextAfter(+infinity, 0) == MAX_VALUE 1936 * nextAfter(+infinity, +infinity) == +infinity 1937 * nextAfter(-infinity, 0) == -MAX_VALUE 1938 * nextAfter(-infinity, -infinity) == -infinity 1939 * 1940 * are naturally handled without any additional testing 1941 */ 1942 1943 /* 1944 * IEEE 754 floating-point numbers are lexicographically 1945 * ordered if treated as signed-magnitude integers. 1946 * Since Java's integers are two's complement, 1947 * incrementing the two's complement representation of a 1948 * logically negative floating-point value *decrements* 1949 * the signed-magnitude representation. Therefore, when 1950 * the integer representation of a floating-point value 1951 * is negative, the adjustment to the representation is in 1952 * the opposite direction from what would initially be expected. 1953 */ 1954 1955 // Branch to descending case first as it is more costly than ascending 1956 // case due to start != 0.0d conditional. 1957 if (start > direction) { // descending 1958 if (start != 0.0d) { 1959 final long transducer = Double.doubleToRawLongBits(start); 1960 return Double.longBitsToDouble(transducer + ((transducer > 0L) ? -1L : 1L)); 1961 } else { // start == 0.0d && direction < 0.0d 1962 return -Double.MIN_VALUE; 1963 } 1964 } else if (start < direction) { // ascending 1965 // Add +0.0 to get rid of a -0.0 (+0.0 + -0.0 => +0.0) 1966 // then bitwise convert start to integer. 1967 final long transducer = Double.doubleToRawLongBits(start + 0.0d); 1968 return Double.longBitsToDouble(transducer + ((transducer >= 0L) ? 1L : -1L)); 1969 } else if (start == direction) { 1970 return direction; 1971 } else { // isNaN(start) || isNaN(direction) 1972 return start + direction; 1973 } 1974 } 1975 1976 /** 1977 * Returns the floating-point number adjacent to the first 1978 * argument in the direction of the second argument. If both 1979 * arguments compare as equal a value equivalent to the second argument 1980 * is returned. 1981 * 1982 * <p> 1983 * Special cases: 1984 * <ul> 1985 * <li> If either argument is a NaN, then NaN is returned. 1986 * 1987 * <li> If both arguments are signed zeros, a value equivalent 1988 * to {@code direction} is returned. 1989 * 1990 * <li> If {@code start} is 1991 * ±{@link Float#MIN_VALUE} and {@code direction} 1992 * has a value such that the result should have a smaller 1993 * magnitude, then a zero with the same sign as {@code start} 1994 * is returned. 1995 * 1996 * <li> If {@code start} is infinite and 1997 * {@code direction} has a value such that the result should 1998 * have a smaller magnitude, {@link Float#MAX_VALUE} with the 1999 * same sign as {@code start} is returned. 2000 * 2001 * <li> If {@code start} is equal to ± 2002 * {@link Float#MAX_VALUE} and {@code direction} has a 2003 * value such that the result should have a larger magnitude, an 2004 * infinity with same sign as {@code start} is returned. 2005 * </ul> 2006 * 2007 * @param start starting floating-point value 2008 * @param direction value indicating which of 2009 * {@code start}'s neighbors or {@code start} should 2010 * be returned 2011 * @return The floating-point number adjacent to {@code start} in the 2012 * direction of {@code direction}. 2013 * @since 1.6 2014 */ 2015 public static float nextAfter(float start, double direction) { 2016 /* 2017 * The cases: 2018 * 2019 * nextAfter(+infinity, 0) == MAX_VALUE 2020 * nextAfter(+infinity, +infinity) == +infinity 2021 * nextAfter(-infinity, 0) == -MAX_VALUE 2022 * nextAfter(-infinity, -infinity) == -infinity 2023 * 2024 * are naturally handled without any additional testing 2025 */ 2026 2027 /* 2028 * IEEE 754 floating-point numbers are lexicographically 2029 * ordered if treated as signed-magnitude integers. 2030 * Since Java's integers are two's complement, 2031 * incrementing the two's complement representation of a 2032 * logically negative floating-point value *decrements* 2033 * the signed-magnitude representation. Therefore, when 2034 * the integer representation of a floating-point value 2035 * is negative, the adjustment to the representation is in 2036 * the opposite direction from what would initially be expected. 2037 */ 2038 2039 // Branch to descending case first as it is more costly than ascending 2040 // case due to start != 0.0f conditional. 2041 if (start > direction) { // descending 2042 if (start != 0.0f) { 2043 final int transducer = Float.floatToRawIntBits(start); 2044 return Float.intBitsToFloat(transducer + ((transducer > 0) ? -1 : 1)); 2045 } else { // start == 0.0f && direction < 0.0f 2046 return -Float.MIN_VALUE; 2047 } 2048 } else if (start < direction) { // ascending 2049 // Add +0.0 to get rid of a -0.0 (+0.0 + -0.0 => +0.0) 2050 // then bitwise convert start to integer. 2051 final int transducer = Float.floatToRawIntBits(start + 0.0f); 2052 return Float.intBitsToFloat(transducer + ((transducer >= 0) ? 1 : -1)); 2053 } else if (start == direction) { 2054 return (float)direction; 2055 } else { // isNaN(start) || isNaN(direction) 2056 return start + (float)direction; 2057 } 2058 } 2059 2060 /** 2061 * Returns the floating-point value adjacent to {@code d} in 2062 * the direction of positive infinity. This method is 2063 * semantically equivalent to {@code nextAfter(d, 2064 * Double.POSITIVE_INFINITY)}; however, a {@code nextUp} 2065 * implementation may run faster than its equivalent 2066 * {@code nextAfter} call. 2067 * 2068 * <p>Special Cases: 2069 * <ul> 2070 * <li> If the argument is NaN, the result is NaN. 2071 * 2072 * <li> If the argument is positive infinity, the result is 2073 * positive infinity. 2074 * 2075 * <li> If the argument is zero, the result is 2076 * {@link Double#MIN_VALUE} 2077 * 2078 * </ul> 2079 * 2080 * @param d starting floating-point value 2081 * @return The adjacent floating-point value closer to positive 2082 * infinity. 2083 * @since 1.6 2084 */ 2085 public static double nextUp(double d) { 2086 // Use a single conditional and handle the likely cases first. 2087 if (d < Double.POSITIVE_INFINITY) { 2088 // Add +0.0 to get rid of a -0.0 (+0.0 + -0.0 => +0.0). 2089 final long transducer = Double.doubleToRawLongBits(d + 0.0D); 2090 return Double.longBitsToDouble(transducer + ((transducer >= 0L) ? 1L : -1L)); 2091 } else { // d is NaN or +Infinity 2092 return d; 2093 } 2094 } 2095 2096 /** 2097 * Returns the floating-point value adjacent to {@code f} in 2098 * the direction of positive infinity. This method is 2099 * semantically equivalent to {@code nextAfter(f, 2100 * Float.POSITIVE_INFINITY)}; however, a {@code nextUp} 2101 * implementation may run faster than its equivalent 2102 * {@code nextAfter} call. 2103 * 2104 * <p>Special Cases: 2105 * <ul> 2106 * <li> If the argument is NaN, the result is NaN. 2107 * 2108 * <li> If the argument is positive infinity, the result is 2109 * positive infinity. 2110 * 2111 * <li> If the argument is zero, the result is 2112 * {@link Float#MIN_VALUE} 2113 * 2114 * </ul> 2115 * 2116 * @param f starting floating-point value 2117 * @return The adjacent floating-point value closer to positive 2118 * infinity. 2119 * @since 1.6 2120 */ 2121 public static float nextUp(float f) { 2122 // Use a single conditional and handle the likely cases first. 2123 if (f < Float.POSITIVE_INFINITY) { 2124 // Add +0.0 to get rid of a -0.0 (+0.0 + -0.0 => +0.0). 2125 final int transducer = Float.floatToRawIntBits(f + 0.0F); 2126 return Float.intBitsToFloat(transducer + ((transducer >= 0) ? 1 : -1)); 2127 } else { // f is NaN or +Infinity 2128 return f; 2129 } 2130 } 2131 2132 /** 2133 * Returns the floating-point value adjacent to {@code d} in 2134 * the direction of negative infinity. This method is 2135 * semantically equivalent to {@code nextAfter(d, 2136 * Double.NEGATIVE_INFINITY)}; however, a 2137 * {@code nextDown} implementation may run faster than its 2138 * equivalent {@code nextAfter} call. 2139 * 2140 * <p>Special Cases: 2141 * <ul> 2142 * <li> If the argument is NaN, the result is NaN. 2143 * 2144 * <li> If the argument is negative infinity, the result is 2145 * negative infinity. 2146 * 2147 * <li> If the argument is zero, the result is 2148 * {@code -Double.MIN_VALUE} 2149 * 2150 * </ul> 2151 * 2152 * @param d starting floating-point value 2153 * @return The adjacent floating-point value closer to negative 2154 * infinity. 2155 * @since 1.8 2156 */ 2157 public static double nextDown(double d) { 2158 if (Double.isNaN(d) || d == Double.NEGATIVE_INFINITY) 2159 return d; 2160 else { 2161 if (d == 0.0) 2162 return -Double.MIN_VALUE; 2163 else 2164 return Double.longBitsToDouble(Double.doubleToRawLongBits(d) + 2165 ((d > 0.0d)?-1L:+1L)); 2166 } 2167 } 2168 2169 /** 2170 * Returns the floating-point value adjacent to {@code f} in 2171 * the direction of negative infinity. This method is 2172 * semantically equivalent to {@code nextAfter(f, 2173 * Float.NEGATIVE_INFINITY)}; however, a 2174 * {@code nextDown} implementation may run faster than its 2175 * equivalent {@code nextAfter} call. 2176 * 2177 * <p>Special Cases: 2178 * <ul> 2179 * <li> If the argument is NaN, the result is NaN. 2180 * 2181 * <li> If the argument is negative infinity, the result is 2182 * negative infinity. 2183 * 2184 * <li> If the argument is zero, the result is 2185 * {@code -Float.MIN_VALUE} 2186 * 2187 * </ul> 2188 * 2189 * @param f starting floating-point value 2190 * @return The adjacent floating-point value closer to negative 2191 * infinity. 2192 * @since 1.8 2193 */ 2194 public static float nextDown(float f) { 2195 if (Float.isNaN(f) || f == Float.NEGATIVE_INFINITY) 2196 return f; 2197 else { 2198 if (f == 0.0f) 2199 return -Float.MIN_VALUE; 2200 else 2201 return Float.intBitsToFloat(Float.floatToRawIntBits(f) + 2202 ((f > 0.0f)?-1:+1)); 2203 } 2204 } 2205 2206 /** 2207 * Returns {@code d} × 2208 * 2<sup>{@code scaleFactor}</sup> rounded as if performed 2209 * by a single correctly rounded floating-point multiply to a 2210 * member of the double value set. See the Java 2211 * Language Specification for a discussion of floating-point 2212 * value sets. If the exponent of the result is between {@link 2213 * Double#MIN_EXPONENT} and {@link Double#MAX_EXPONENT}, the 2214 * answer is calculated exactly. If the exponent of the result 2215 * would be larger than {@code Double.MAX_EXPONENT}, an 2216 * infinity is returned. Note that if the result is subnormal, 2217 * precision may be lost; that is, when {@code scalb(x, n)} 2218 * is subnormal, {@code scalb(scalb(x, n), -n)} may not equal 2219 * <i>x</i>. When the result is non-NaN, the result has the same 2220 * sign as {@code d}. 2221 * 2222 * <p>Special cases: 2223 * <ul> 2224 * <li> If the first argument is NaN, NaN is returned. 2225 * <li> If the first argument is infinite, then an infinity of the 2226 * same sign is returned. 2227 * <li> If the first argument is zero, then a zero of the same 2228 * sign is returned. 2229 * </ul> 2230 * 2231 * @param d number to be scaled by a power of two. 2232 * @param scaleFactor power of 2 used to scale {@code d} 2233 * @return {@code d} × 2<sup>{@code scaleFactor}</sup> 2234 * @since 1.6 2235 */ 2236 public static double scalb(double d, int scaleFactor) { 2237 /* 2238 * This method does not need to be declared strictfp to 2239 * compute the same correct result on all platforms. When 2240 * scaling up, it does not matter what order the 2241 * multiply-store operations are done; the result will be 2242 * finite or overflow regardless of the operation ordering. 2243 * However, to get the correct result when scaling down, a 2244 * particular ordering must be used. 2245 * 2246 * When scaling down, the multiply-store operations are 2247 * sequenced so that it is not possible for two consecutive 2248 * multiply-stores to return subnormal results. If one 2249 * multiply-store result is subnormal, the next multiply will 2250 * round it away to zero. This is done by first multiplying 2251 * by 2 ^ (scaleFactor % n) and then multiplying several 2252 * times by 2^n as needed where n is the exponent of number 2253 * that is a covenient power of two. In this way, at most one 2254 * real rounding error occurs. If the double value set is 2255 * being used exclusively, the rounding will occur on a 2256 * multiply. If the double-extended-exponent value set is 2257 * being used, the products will (perhaps) be exact but the 2258 * stores to d are guaranteed to round to the double value 2259 * set. 2260 * 2261 * It is _not_ a valid implementation to first multiply d by 2262 * 2^MIN_EXPONENT and then by 2 ^ (scaleFactor % 2263 * MIN_EXPONENT) since even in a strictfp program double 2264 * rounding on underflow could occur; e.g. if the scaleFactor 2265 * argument was (MIN_EXPONENT - n) and the exponent of d was a 2266 * little less than -(MIN_EXPONENT - n), meaning the final 2267 * result would be subnormal. 2268 * 2269 * Since exact reproducibility of this method can be achieved 2270 * without any undue performance burden, there is no 2271 * compelling reason to allow double rounding on underflow in 2272 * scalb. 2273 */ 2274 2275 // magnitude of a power of two so large that scaling a finite 2276 // nonzero value by it would be guaranteed to over or 2277 // underflow; due to rounding, scaling down takes an 2278 // additional power of two which is reflected here 2279 final int MAX_SCALE = DoubleConsts.MAX_EXPONENT + -DoubleConsts.MIN_EXPONENT + 2280 DoubleConsts.SIGNIFICAND_WIDTH + 1; 2281 int exp_adjust = 0; 2282 int scale_increment = 0; 2283 double exp_delta = Double.NaN; 2284 2285 // Make sure scaling factor is in a reasonable range 2286 2287 if(scaleFactor < 0) { 2288 scaleFactor = Math.max(scaleFactor, -MAX_SCALE); 2289 scale_increment = -512; 2290 exp_delta = twoToTheDoubleScaleDown; 2291 } 2292 else { 2293 scaleFactor = Math.min(scaleFactor, MAX_SCALE); 2294 scale_increment = 512; 2295 exp_delta = twoToTheDoubleScaleUp; 2296 } 2297 2298 // Calculate (scaleFactor % +/-512), 512 = 2^9, using 2299 // technique from "Hacker's Delight" section 10-2. 2300 int t = (scaleFactor >> 9-1) >>> 32 - 9; 2301 exp_adjust = ((scaleFactor + t) & (512 -1)) - t; 2302 2303 d *= powerOfTwoD(exp_adjust); 2304 scaleFactor -= exp_adjust; 2305 2306 while(scaleFactor != 0) { 2307 d *= exp_delta; 2308 scaleFactor -= scale_increment; 2309 } 2310 return d; 2311 } 2312 2313 /** 2314 * Returns {@code f} × 2315 * 2<sup>{@code scaleFactor}</sup> rounded as if performed 2316 * by a single correctly rounded floating-point multiply to a 2317 * member of the float value set. See the Java 2318 * Language Specification for a discussion of floating-point 2319 * value sets. If the exponent of the result is between {@link 2320 * Float#MIN_EXPONENT} and {@link Float#MAX_EXPONENT}, the 2321 * answer is calculated exactly. If the exponent of the result 2322 * would be larger than {@code Float.MAX_EXPONENT}, an 2323 * infinity is returned. Note that if the result is subnormal, 2324 * precision may be lost; that is, when {@code scalb(x, n)} 2325 * is subnormal, {@code scalb(scalb(x, n), -n)} may not equal 2326 * <i>x</i>. When the result is non-NaN, the result has the same 2327 * sign as {@code f}. 2328 * 2329 * <p>Special cases: 2330 * <ul> 2331 * <li> If the first argument is NaN, NaN is returned. 2332 * <li> If the first argument is infinite, then an infinity of the 2333 * same sign is returned. 2334 * <li> If the first argument is zero, then a zero of the same 2335 * sign is returned. 2336 * </ul> 2337 * 2338 * @param f number to be scaled by a power of two. 2339 * @param scaleFactor power of 2 used to scale {@code f} 2340 * @return {@code f} × 2<sup>{@code scaleFactor}</sup> 2341 * @since 1.6 2342 */ 2343 public static float scalb(float f, int scaleFactor) { 2344 // magnitude of a power of two so large that scaling a finite 2345 // nonzero value by it would be guaranteed to over or 2346 // underflow; due to rounding, scaling down takes an 2347 // additional power of two which is reflected here 2348 final int MAX_SCALE = FloatConsts.MAX_EXPONENT + -FloatConsts.MIN_EXPONENT + 2349 FloatConsts.SIGNIFICAND_WIDTH + 1; 2350 2351 // Make sure scaling factor is in a reasonable range 2352 scaleFactor = Math.max(Math.min(scaleFactor, MAX_SCALE), -MAX_SCALE); 2353 2354 /* 2355 * Since + MAX_SCALE for float fits well within the double 2356 * exponent range and + float -> double conversion is exact 2357 * the multiplication below will be exact. Therefore, the 2358 * rounding that occurs when the double product is cast to 2359 * float will be the correctly rounded float result. Since 2360 * all operations other than the final multiply will be exact, 2361 * it is not necessary to declare this method strictfp. 2362 */ 2363 return (float)((double)f*powerOfTwoD(scaleFactor)); 2364 } 2365 2366 // Constants used in scalb 2367 static double twoToTheDoubleScaleUp = powerOfTwoD(512); 2368 static double twoToTheDoubleScaleDown = powerOfTwoD(-512); 2369 2370 /** 2371 * Returns a floating-point power of two in the normal range. 2372 */ 2373 static double powerOfTwoD(int n) { 2374 assert(n >= DoubleConsts.MIN_EXPONENT && n <= DoubleConsts.MAX_EXPONENT); 2375 return Double.longBitsToDouble((((long)n + (long)DoubleConsts.EXP_BIAS) << 2376 (DoubleConsts.SIGNIFICAND_WIDTH-1)) 2377 & DoubleConsts.EXP_BIT_MASK); 2378 } 2379 2380 /** 2381 * Returns a floating-point power of two in the normal range. 2382 */ 2383 static float powerOfTwoF(int n) { 2384 assert(n >= FloatConsts.MIN_EXPONENT && n <= FloatConsts.MAX_EXPONENT); 2385 return Float.intBitsToFloat(((n + FloatConsts.EXP_BIAS) << 2386 (FloatConsts.SIGNIFICAND_WIDTH-1)) 2387 & FloatConsts.EXP_BIT_MASK); 2388 } 2389 }