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.FloatConsts; 30 import jdk.internal.math.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 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 * | ```
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.math.BigDecimal;
29 import java.util.Random;
30 import jdk.internal.math.FloatConsts;
31 import jdk.internal.math.DoubleConsts;
32 import jdk.internal.HotSpotIntrinsicCandidate;
33
34 /**
35 * The class {@code Math} contains methods for performing basic
36 * numeric operations such as the elementary exponential, logarithm,
37 * square root, and trigonometric functions.
38 *
39 * <p>Unlike some of the numeric methods of class
40 * {@code StrictMath}, all implementations of the equivalent
41 * functions of class {@code Math} are not defined to return the
42 * bit-for-bit same results. This relaxation permits
43 * better-performing implementations where strict reproducibility is
44 * not required.
45 *
46 * <p>By default many of the {@code Math} methods simply call
47 * the equivalent method in {@code StrictMath} for their
48 * implementation. Code generators are encouraged to use
``` 1431 * value. If either value is NaN, then the result is NaN. Unlike 1432 * the numerical comparison operators, this method considers 1433 * negative zero to be strictly smaller than positive zero. If one 1434 * argument is positive zero and the other is negative zero, the 1435 * result is negative zero. 1436 * 1437 * @param a an argument. 1438 * @param b another argument. 1439 * @return the smaller of {@code a} and {@code b}. 1440 */ 1441 public static double min(double a, double b) { 1442 if (a != a) 1443 return a; // a is NaN 1444 if ((a == 0.0d) && 1445 (b == 0.0d) && 1446 (Double.doubleToRawLongBits(b) == negativeZeroDoubleBits)) { 1447 // Raw conversion ok since NaN can't map to -0.0. 1448 return b; 1449 } 1450 return (a <= b) ? a : b; 1451 } 1452 1453 /** 1454 * Returns the fused multiply-accumulate of the three arguments; 1455 * that is, returns the exact product of the first two arguments 1456 * summed with the third argument and then rounded once to the 1457 * nearest {@code double}. 1458 * 1459 * The rounding is done using the {@linkplain 1460 * java.math.RoundingMode#HALF_EVEN round to nearest even 1461 * rounding mode}. 1462 * 1463 * In contrast, if {@code a * b + c} is evaluated as a regular 1464 * floating-point expression, two rounding errors are involved, 1465 * the first for the multiply operation, the second for the 1466 * addition operation. 1467 * 1468 * <p>Special cases: 1469 * <ul> 1470 * <li> If any argument is NaN, the result is NaN. 1471 * 1472 * <li> If one of the first two arguments is infinite and the 1473 * other is zero, the result is NaN. 1474 * 1475 * <li> If the exact product of the first two arguments is infinite 1476 * (in other words, at least one of the arguments is infinite and 1477 * the other is neither zero nor NaN) and the third argument is an 1478 * infinity of the opposite sign, the result is NaN. 1479 * 1480 * </ul> 1481 * 1482 * <p>Note that {@code fusedMac(a, 1.0, c)} returns the same 1483 * result as ({@code a + c}). However, 1484 * {@code fusedMac(a, b, +0.0)} does <em>not</em> always return the 1485 * same result as ({@code a * b}) since 1486 * {@code fusedMac(-0.0, +0.0, +0.0)} is {@code +0.0} while 1487 * ({@code 0.0 * +0.0}) is {@code -0.0}; {@code fusedMac(a, b, -0.0)} is 1488 * equivalent to ({@code a * b}) however. 1489 * 1490 * @param a a value 1491 * @param b a value 1492 * @param c a value 1493 * 1494 * @return (<i>a</i> × <i>b</i> + <i>c</i>) 1495 * computed, as if with unlimited range and precision, and rounded 1496 * once to the nearest {@code double} value 1497 */ 1498 // @HotSpotIntrinsicCandidate 1499 public static double fusedMac(double a, double b, double c) { 1500 if (!Double.isFinite(a) || 1501 !Double.isFinite(b) || 1502 !Double.isFinite(c)) { 1503 // Infinite and NaN arithmetic is not quite the same with 1504 // two roundings as opposed to just one. With two 1505 // roundings, the product and overflow and if the addend 1506 // is infinite, a spurious NaN can be produced. 1507 1508 if (Double.isNaN(a) || Double.isNaN(b) || Double.isNaN(c)) { 1509 return Double.NaN; 1510 } else { // One or more infinities in the input 1511 if ((Double.isInfinite(a) && b == 0.0) || 1512 (Double.isInfinite(b) && a == 0.0)) { 1513 return Double.NaN; 1514 } else { 1515 double product = a * b; 1516 double result = product + c; 1517 if (Double.isInfinite(product) && 1518 (!Double.isInfinite(a) && !Double.isInfinite(b))) { 1519 // Intermediate overflow; might cause a 1520 // spurious NaN with added to infinite c. 1521 return c; 1522 } 1523 return result; 1524 } 1525 } 1526 } if (a == 1.0 || // Could just return b + c 1527 b == 1.0 || // Could just return a + c 1528 a == 0.0 || // Handle any signed zero issues 1529 b == 0.0 || // Handle any signed zero issues 1530 c == 0.0) { // Could be +0.0 or -0.0) 1531 // The special cases of a == 1.0, b == 1.0, and c == 0.0 1532 // are handled as double operations rather than falling 1533 // back on BigDecimal. The case where a == 1.0 or b == 1.0 1534 // would be handled correctly by the BigDecimal code 1535 // below, unlike the signed zero case where the exact 1536 // product is -0.0 and c is -0.0. 1537 1538 // As noted above, if c is zero, it must still be added in 1539 // since a negative zero can change the sign of the final 1540 // result if the product is zero. At the cost of 1541 // additional checks on a and b, the addition of a zero c 1542 // could be avoided. 1543 1544 return a * b + c; 1545 } else { 1546 // The set of values representable in BigDecimal includes 1547 // neither signed zero nor infinities nor NaN. The logic 1548 // above handles those cases. All finite double values are 1549 // representable in BigDecimal. The code below exactly 1550 // converts a, b, and c to their equivalent BigDecimal 1551 // numbers, exactly computes the product and sum as 1552 // appropriate, and then performs a single rounding to 1553 // double using the round to nearest rounding mode. 1554 return (((new BigDecimal(a)).multiply(new BigDecimal(b))). 1555 add(new BigDecimal(c))).doubleValue(); 1556 } 1557 } 1558 1559 /** 1560 * Returns the fused multiply-accumulate of the three arguments; 1561 * that is, returns the exact product of the first two arguments 1562 * summed with the third argument and then rounded once to the 1563 * nearest {@code float}. 1564 * 1565 * The rounding is done using the {@linkplain 1566 * java.math.RoundingMode#HALF_EVEN round to nearest even 1567 * rounding mode}. 1568 * 1569 * In contrast, if {@code a * b + c} is evaluated as a regular 1570 * floating-point expression, two rounding errors are involved, 1571 * the first for the multiply operation, the second for the 1572 * addition operation. 1573 * 1574 * <p>Special cases: 1575 * <ul> 1576 * <li> If any argument is NaN, the result is NaN. 1577 * 1578 * <li> If one of the first two arguments is infinite and the 1579 * other is zero, the result is NaN. 1580 * 1581 * <li> If the exact product of the first two arguments is infinite 1582 * (in other words, at least one of the arguments is infinite and 1583 * the other is neither zero nor NaN) and the third argument is an 1584 * infinity of the opposite sign, the result is NaN. 1585 * 1586 * </ul> 1587 * 1588 * <p>Note that {@code fusedMac(a, 1.0f, c)} returns the same 1589 * result as ({@code a + c}). However, 1590 * {@code fusedMac(a, b, +0.0f)} does <em>not</em> always return the 1591 * same result as ({@code a * b}) since 1592 * {@code fusedMac(-0.0f, +0.0f, +0.0f)} is {@code +0.0f} while 1593 * ({@code 0.0f * +0.0f}) is {@code -0.0f}; {@code fusedMac(a, b, -0.0f)} is 1594 * equivalent to ({@code a * b}) however. 1595 * 1596 * @param a a value 1597 * @param b a value 1598 * @param c a value 1599 * 1600 * @return (<i>a</i> × <i>b</i> + <i>c</i>) 1601 * computed, as if with unlimited range and precision, and rounded 1602 * once to the nearest {@code float} value 1603 */ 1604 // @HotSpotIntrinsicCandidate 1605 public static float fusedMac(float a, float b, float c) { 1606 // Since double has more than twice the precision of float, 1607 // the multiply of a * b is exact in double. The add of c to 1608 // the product then has one rounded error. Since double 1609 // moreover has more than 2p + 2 precision compared to float, 1610 // the double rounding of (a*b + c) from the double format to 1611 // the float format is equivalent to rounding the result 1612 // directly to float precision. 1613 return (float)(((double) a * (double) b ) + (double) c); 1614 } 1615 1616 /** 1617 * Returns the size of an ulp of the argument. An ulp, unit in 1618 * the last place, of a {@code double} value is the positive 1619 * distance between this floating-point value and the {@code 1620 * double} value next larger in magnitude. Note that for non-NaN 1621 * <i>x</i>, <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>. 1622 * 1623 * <p>Special Cases: 1624 * <ul> 1625 * <li> If the argument is NaN, then the result is NaN. 1626 * <li> If the argument is positive or negative infinity, then the 1627 * result is positive infinity. 1628 * <li> If the argument is positive or negative zero, then the result is 1629 * {@code Double.MIN_VALUE}. 1630 * <li> If the argument is ±{@code Double.MAX_VALUE}, then 1631 * the result is equal to 2<sup>971</sup>. 1632 * </ul> 1633 * |