Summary

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

Problem

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

Solution

Ported the atanh() function from fdlibm.

Specification

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

/**
     * Returns the inverse hyperbolic tangent of a {@code double} value.
     * The inverse hyperbolic tangent of <i>x</i> is defined to be the function such that
     * atanh({@linkplain Math#tanh tanh(<i>x</i>)}) = <i>x</i> for any <i>x</i>.
     * Note that the domain of the exact atanh is (-1; 1), the range is unrestricted.
     *
     * <p>Special cases:
     * <ul>
     *
     * <li>If the argument is NaN, then the result is NaN.
     *
     * <li>If the argument is zero, then the result is a zero with the
     * same sign as the argument.
     *
     * <li>If the argument is {@code +1.0}, then the result is
     * positive infinity.
     *
     * <li>If the argument is {@code -1.0}, then the result is
     * negative infinity.
     *
     * <li>If the argument is greater than {@code 1.0} in magnitude, then the result is NaN.
     *
     * </ul>
     *
     * @param   x The number whose inverse hyperbolic tangent is to be returned.
     * @return  The inverse hyperbolic tangent of {@code x}.
     * @since 27
     */
    public static double atanh(double x) {
        return FdLibm.Atanh.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 9421b41620b..a8f67ef58ba 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 acosh}, {@code hypot},
- * {@code expm1}, and {@code log1p}.
+ * {@code asinh}, {@code acosh},{@code atanh},
+ * {@code hypot}, {@code expm1}, and {@code log1p}.
  *
  * <p>
  * The platform uses signed two's complement integer arithmetic with
@@ -2222,6 +2222,38 @@ public static double acosh(double x) {
         return FdLibm.Acosh.compute(x);
     }

+    /**
+     * Returns the inverse hyperbolic tangent of a {@code double} value.
+     * The inverse hyperbolic tangent of <i>x</i> is defined to be the function such that
+     * atanh({@linkplain Math#tanh tanh(<i>x</i>)}) = <i>x</i> for any <i>x</i>.
+     * Note that the domain of the exact atanh is (-1; 1), the range is unrestricted.
+     *
+     * <p>Special cases:
+     * <ul>
+     *
+     * <li>If the argument is NaN, then the result is NaN.
+     *
+     * <li>If the argument is zero, then the result is a zero with the
+     * same sign as the argument.
+     *
+     * <li>If the argument is {@code +1.0}, then the result is
+     * positive infinity.
+     *
+     * <li>If the argument is {@code -1.0}, then the result is
+     * negative infinity.
+     *
+     * <li>If the argument is greater than {@code 1.0} in magnitude, then the result is NaN.
+     *
+     * </ul>
+     *
+     * @param   x The number whose inverse hyperbolic tangent is to be returned.
+     * @return  The inverse hyperbolic tangent of {@code x}.
+     * @since 27
+     */
+    public static double atanh(double x) {
+        return FdLibm.Atanh.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 4f729fe82cb..38a5328fa0b 100644
--- a/src/java.base/share/classes/java/lang/Math.java
+++ b/src/java.base/share/classes/java/lang/Math.java
@@ -109,7 +109,7 @@
  * 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 acosh acosh}, {@link hypot hypot}, and {@link pow pow}.
+ * {@link acosh acosh}, {@link atanh atanh}, {@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
@@ -2814,6 +2814,38 @@ public static double acosh(double x) {
         return StrictMath.acosh(x);
     }

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