Summary

Add acosh() function to Math.java and StrictMath.java.

Problem

The IEEE 754 2019 standard recommends platform include various "additional mathematical operations" (section 9.2). The acosh (inverse hyperbolic cosine) function if one of those.

Solution

Ported the acosh() function from fdlibm.

Specification

In both java.lang.Math and java.lang.StrictMath added:

/**
     * Returns the inverse hyperbolic cosine of a {@code double} value.
     * The inverse hyperbolic cosine of <i>x</i> is defined to be a function such that
     *  acosh({@linkplain Math#cosh cosh(<i>x</i>)}) = <i>x</i> for any <i>x</i>.
     *  Note that range of the exact acosh is >= 1.
     * <p>Special cases:
     * <ul>
     *
     * <li>If the argument is positive infinity, then the result is
     * positive infinity
     *
     * <li>If the argument less than 1, then the result is NaN.
     *
     * <li>If the argument is NaN, then the result is NaN.
     *
     * </ul>
     * @param   x The number whose inverse hyperbolic cosine is to be returned.
     * @return  The inverse hyperbolic cosine of {@code x}.
     * @since 27
     */
    public static double acosh(double x) {
        return FdLibm.Acosh.compute(x);
    }

diff --git a/src/java.base/share/classes/java/lang/StrictMath.java b/src/java.base/share/classes/java/lang/StrictMath.java
index 901b3295d5b..677aed63ea0 100644
--- a/src/java.base/share/classes/java/lang/StrictMath.java
+++ b/src/java.base/share/classes/java/lang/StrictMath.java
@@ -76,8 +76,8 @@
  * {@code exp}, {@code log}, {@code log10},
  * {@code cbrt}, {@code atan2}, {@code pow},
  * {@code sinh}, {@code cosh}, {@code tanh},
- * {@code asinh}, {@code hypot}, {@code expm1},
- * and {@code log1p}.
+ * {@code asinh}, {@code acosh}, {@code hypot},
+ * {@code expm1}, and {@code log1p}.
  *
  * <p>
  * The platform uses signed two's complement integer arithmetic with
@@ -2199,6 +2199,30 @@ public static double asinh(double x) {
         return FdLibm.Asinh.compute(x);
     }

+    /**
+     * Returns the inverse hyperbolic cosine of a {@code double} value.
+     * The inverse hyperbolic cosine of <i>x</i> is defined to be a function such that
+     *  acosh({@linkplain Math#cosh cosh(<i>x</i>)}) = <i>x</i> for any <i>x</i>.
+     *  Note that range of the exact acosh is >= 1.
+     * <p>Special cases:
+     * <ul>
+     *
+     * <li>If the argument is positive infinity, then the result is
+     * positive infinity
+     *
+     * <li>If the argument less than 1, then the result is NaN.
+     *
+     * <li>If the argument is NaN, then the result is NaN.
+     *
+     * </ul>
+     * @param   x The number whose inverse hyperbolic cosine is to be returned.
+     * @return  The inverse hyperbolic cosine of {@code x}.
+     * @since 27
+     */
+    public static double acosh(double x) {
+        return FdLibm.Acosh.compute(x);
+    }
+
     /**
      * Returns sqrt(<i>x</i><sup>2</sup>&nbsp;+<i>y</i><sup>2</sup>)
      * without intermediate overflow or underflow.

diff --git a/src/java.base/share/classes/java/lang/Math.java b/src/java.base/share/classes/java/lang/Math.java
index 6270011b96d..02f85dde3b0 100644
--- a/src/java.base/share/classes/java/lang/Math.java
+++ b/src/java.base/share/classes/java/lang/Math.java
@@ -109,9 +109,9 @@
  * acos acos}, {@link atan atan}, {@link exp exp}, {@link expm1
  * expm1}, {@link log log}, {@link log10 log10}, {@link log1p log1p},
  * {@link sinh sinh}, {@link cosh cosh}, {@link tanh tanh}, {@link asinh asinh},
- * {@link hypot hypot}, and {@link pow pow}.  (The {@link sqrt sqrt}
- * operation is a required part of IEEE 754 from a different section
- * of the standard.) The special case behavior of the recommended
+ * {@link acosh acosh}, {@link hypot hypot}, and {@link pow pow}.
+ * (The {@link sqrt sqrt} operation is a required part of IEEE 754 from a
+ * different section of the standard.) The special case behavior of the recommended
  * operations generally follows the guidance of the IEEE 754
  * standard. However, the {@code pow} method defines different
  * behavior for some arguments, as noted in its {@linkplain pow
@@ -2788,6 +2788,32 @@ public static double asinh(double x) {
         return StrictMath.asinh(x);
     }

+    /**
+     * Returns the inverse hyperbolic cosine of a {@code double} value.
+     * The inverse hyperbolic cosine of <i>x</i> is defined to be a function such that
+     *  acosh({@linkplain Math#cosh cosh(<i>x</i>)}) = <i>x</i> for any <i>x</i>.
+     *  Note that range of the exact acosh is >= 1.
+     * <p>Special cases:
+     * <ul>
+     *
+     * <li>If the argument is positive infinity, then the result is
+     * positive infinity
+     *
+     * <li>If the argument less than 1, then the result is NaN.
+     *
+     * <li>If the argument is NaN, then the result is NaN.
+     *
+     * <p>The computed result must be within 2.5 ulps of the exact result.
+     *
+     * </ul>
+     * @param   x The number whose inverse hyperbolic cosine is to be returned.
+     * @return  The inverse hyperbolic cosine of {@code x}.
+     * @since 27
+     */
+    public static double acosh(double x) {
+        return StrictMath.acosh(x);
+    }
+
     /**
      * Returns sqrt(<i>x</i><sup>2</sup>&nbsp;+<i>y</i><sup>2</sup>)
      * without intermediate overflow or underflow.