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 add of the three arguments; that is,
1455 * returns the exact product of the first two arguments summed
1456 * with the third argument and then rounded once to the nearest
1457 * {@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 fma(a, 1.0, c)} returns the same
1483 * result as ({@code a + c}). However,
1484 * {@code fma(a, b, +0.0)} does <em>not</em> always return the
1485 * same result as ({@code a * b}) since
1486 * {@code fma(-0.0, +0.0, +0.0)} is {@code +0.0} while
1487 * ({@code -0.0 * +0.0}) is {@code -0.0}; {@code fma(a, b, -0.0)} is
1488 * equivalent to ({@code a * b}) however.
1489 *
1490 * @apiNote This method corresponds to the fusedMultiplyAdd
1491 * operation defined in IEEE 754-2008.
1492 *
1493 * @param a a value
1494 * @param b a value
1495 * @param c a value
1496 *
1497 * @return (<i>a</i> × <i>b</i> + <i>c</i>)
1498 * computed, as if with unlimited range and precision, and rounded
1499 * once to the nearest {@code double} value
1500 */
1501 // @HotSpotIntrinsicCandidate
1502 public static double fma(double a, double b, double c) {
1503 /*
1504 * Infinity and NaN arithmetic is not quite the same with two
1505 * roundings as opposed to just one so the simple expression
1506 * "a * b + c" cannot always be used to compute the correct
1507 * result. With two roundings, the product can overflow and
1508 * if the addend is infinite, a spurious NaN can be produced
1509 * if the infinity from the overflow and the infinite addend
1510 * have opposite signs.
1511 */
1512
1513 // First, screen for and handle non-finite input values whose
1514 // arithmetic is not supported by BigDecimal.
1515 if (Double.isNaN(a) || Double.isNaN(b) || Double.isNaN(c)) {
1516 return Double.NaN;
1517 } else { // All inputs non-NaN
1518 boolean infiniteA = Double.isInfinite(a);
1519 boolean infiniteB = Double.isInfinite(b);
1520 boolean infiniteC = Double.isInfinite(c);
1521 double result;
1522
1523 if (infiniteA || infiniteB || infiniteC) {
1524 if (infiniteA && b == 0.0 ||
1525 infiniteB && a == 0.0 ) {
1526 return Double.NaN;
1527 }
1528 // Store product in a double field to cause an
1529 // overflow even if non-strictfp evaluation is being
1530 // used.
1531 double product = a * b;
1532 if (Double.isInfinite(product) && !infiniteA && !infiniteB) {
1533 // Intermediate overflow; might cause a
1534 // spurious NaN if added to infinite c.
1535 assert Double.isInfinite(c);
1536 return c;
1537 } else {
1538 result = product + c;
1539 assert !Double.isFinite(result);
1540 return result;
1541 }
1542 } else { // All inputs finite
1543 BigDecimal product = (new BigDecimal(a)).multiply(new BigDecimal(b));
1544 if (c == 0.0) { // Positive or negative zero
1545 // If the product is an exact zero, use a
1546 // floating-point expression to compute the sign
1547 // of the zero final result. The product is an
1548 // exact zero if and only if at least one of a and
1549 // b is zero.
1550 if (a == 0.0 || b == 0.0) {
1551 return a * b + c;
1552 } else {
1553 // The sign of a zero addend doesn't matter if
1554 // the product is nonzero. The sign of a zero
1555 // addend is not factored in the result if the
1556 // exact product is nonzero but underflows to
1557 // zero; see IEEE-754 2008 section 6.3 "The
1558 // sign bit".
1559 return product.doubleValue();
1560 }
1561 } else {
1562 return product.add(new BigDecimal(c)).doubleValue();
1563 }
1564 }
1565 }
1566 }
1567
1568 /**
1569 * Returns the fused multiply add of the three arguments; that is,
1570 * returns the exact product of the first two arguments summed
1571 * with the third argument and then rounded once to the nearest
1572 * {@code float}.
1573 *
1574 * The rounding is done using the {@linkplain
1575 * java.math.RoundingMode#HALF_EVEN round to nearest even
1576 * rounding mode}.
1577 *
1578 * In contrast, if {@code a * b + c} is evaluated as a regular
1579 * floating-point expression, two rounding errors are involved,
1580 * the first for the multiply operation, the second for the
1581 * addition operation.
1582 *
1583 * <p>Special cases:
1584 * <ul>
1585 * <li> If any argument is NaN, the result is NaN.
1586 *
1587 * <li> If one of the first two arguments is infinite and the
1588 * other is zero, the result is NaN.
1589 *
1590 * <li> If the exact product of the first two arguments is infinite
1591 * (in other words, at least one of the arguments is infinite and
1592 * the other is neither zero nor NaN) and the third argument is an
1593 * infinity of the opposite sign, the result is NaN.
1594 *
1595 * </ul>
1596 *
1597 * <p>Note that {@code fma(a, 1.0f, c)} returns the same
1598 * result as ({@code a + c}). However,
1599 * {@code fma(a, b, +0.0f)} does <em>not</em> always return the
1600 * same result as ({@code a * b}) since
1601 * {@code fma(-0.0f, +0.0f, +0.0f)} is {@code +0.0f} while
1602 * ({@code -0.0f * +0.0f}) is {@code -0.0f}; {@code fma(a, b, -0.0f)} is
1603 * equivalent to ({@code a * b}) however.
1604 *
1605 * @apiNote This method corresponds to the fusedMultiplyAdd
1606 * operation defined in IEEE 754-2008.
1607 *
1608 * @param a a value
1609 * @param b a value
1610 * @param c a value
1611 *
1612 * @return (<i>a</i> × <i>b</i> + <i>c</i>)
1613 * computed, as if with unlimited range and precision, and rounded
1614 * once to the nearest {@code float} value
1615 */
1616 // @HotSpotIntrinsicCandidate
1617 public static float fma(float a, float b, float c) {
1618 /*
1619 * Since the double format has more than twice the precision
1620 * of the float format, the multiply of a * b is exact in
1621 * double. The add of c to the product then incurs one
1622 * rounding error. Since the double format moreover has more
1623 * than (2p + 2) precision bits compared to the p bits of the
1624 * float format, the two roundings of (a * b + c), first to
1625 * the double format and then secondarily to the float format,
1626 * are equivalent to rounding the intermediate result directly
1627 * to the float format.
1628 *
1629 * In terms of strictfp vs default-fp concerns related to
1630 * overflow and underflow, since
1631 *
1632 * (Float.MAX_VALUE * Float.MAX_VALUE) << Double.MAX_VALUE
1633 * (Float.MIN_VALUE * Float.MIN_VALUE) >> Double.MIN_VALUE
1634 *
1635 * neither the multiply nor add will overflow or underflow in
1636 * double. Therefore, it is not necessary for this method to
1637 * be declared strictfp to have reproducible
1638 * behavior. However, it is necessary to explicitly store down
1639 * to a float variable to avoid returning a value in the float
1640 * extended value set.
1641 */
1642 float result = (float)(((double) a * (double) b ) + (double) c);
1643 return result;
1644 }
1645
1646 /**
1647 * Returns the size of an ulp of the argument. An ulp, unit in
1648 * the last place, of a {@code double} value is the positive
1649 * distance between this floating-point value and the {@code
1650 * double} value next larger in magnitude. Note that for non-NaN
1651 * <i>x</i>, <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
1652 *
1653 * <p>Special Cases:
1654 * <ul>
1655 * <li> If the argument is NaN, then the result is NaN.
1656 * <li> If the argument is positive or negative infinity, then the
1657 * result is positive infinity.
1658 * <li> If the argument is positive or negative zero, then the result is
1659 * {@code Double.MIN_VALUE}.
1660 * <li> If the argument is ±{@code Double.MAX_VALUE}, then
1661 * the result is equal to 2<sup>971</sup>.
1662 * </ul>
1663 *
|