std::atanh(std::complex)(3)

💅 std::atanh(std::complex) — the C++ Standard Library one, bestie

Okay so picture this: it's a (3) manual page, it lives in the C++ Standard Library, and its whole entire personality is std::atanh(std::complex). That's the name, that's the vibe, we move. 🦋

---

✨ Synopsis ✨

First things first, she's Defined in header <complex> — don't forget to bring her along.

template< class T >                       (since C++11)
complex<T> atanh( const complex<T>& z );

So what does she do? She computes the complex arc hyperbolic tangent of z, and the branch cuts sit outside the interval [−1; +1] along the real axis. Lowkey iconic behavior tbh. 🎀

---

🌸 Parameters 🌸

• z — a complex value. that's it, that's the whole parameter list, she's low-maintenance.

---

👑 Return value 👑

If literally no errors happen (a blessed day ✨), you get the complex arc hyperbolic tangent of z back, and it lives in the range of a half-strip that is mathematically unbounded along the real axis and sits in the interval [−iπ/2; +iπ/2] along the imaginary axis. Slay.

💀 Error handling and special values 💀

Errors get reported consistent with math_errhandling. fr fr, that's the system.

If the implementation supports IEEE floating-point arithmetic, here's the whole mood board:

• std::atanh(std::conj(z)) == std::conj(std::atanh(z))
• std::atanh(-z) == -std::atanh(z)
• If z is (+0,+0), the result is (+0,+0)
• If z is (+0,NaN), the result is (+0,NaN)
• If z is (+1,+0), the result is (+∞,+0) and FE_DIVBYZERO is raised
• If z is (x,+∞) (for any finite positive x), the result is (+0,π/2)
• If z is (x,NaN) (for any finite nonzero x), the result is (NaN,NaN) and FE_INVALID may be raised
• If z is (+∞,y) (for any finite positive y), the result is (+0,π/2)
• If z is (+∞,+∞), the result is (+0,π/2)
• If z is (+∞,NaN), the result is (+0,NaN)
• If z is (NaN,y) (for any finite y), the result is (NaN,NaN) and FE_INVALID may be raised
• If z is (NaN,+∞), the result is (±0,π/2) (the sign of the real part is unspecified — yeah, she's mysterious like that 🙈)
• If z is (NaN,NaN), the result is (NaN,NaN)

---

🧚 Notes 🧚

Bestie, this is the part where we get a little pedantic and honestly we should. 💅

Even though the C++ standard calls this function "complex arc hyperbolic tangent", the inverse functions of the hyperbolic functions are actually the area functions. Their argument is the area of a hyperbolic sector, not an arc. So the correct name is "complex inverse hyperbolic tangent" and, less common, "complex area hyperbolic tangent". The way that etymology stayed relevant 😭

Inverse hyperbolic tangent is a multivalued function and she requires a branch cut on the complex plane. By convention the branch cut is placed at the line segments (-∞,-1] and [+1,+∞) of the real axis.

The mathematical definition of the principal value of the inverse hyperbolic tangent is:

atanh z = ( ln(1+z) - ln(1-z) ) / 2

And for any z:

atanh(z) = atan(iz) / i

---

🌈 Example 🌈

// Run this code

#include <complex>
#include <iostream>

int main()
{
    std::cout << std::fixed;
    std::complex<double> z1(2.0, 0.0);
    std::cout << "atanh" << z1 << " = " << std::atanh(z1) << '\n';

    std::complex<double> z2(2.0, -0.0);
    std::cout << "atanh" << z2 << " (the other side of the cut) = "
              << std::atanh(z2) << '\n';

    // for any z, atanh(z) = atanh(iz) / i
    std::complex<double> z3(1.0, 2.0);
    std::complex<double> i(0.0, 1.0);
    std::cout << "atanh" << z3 << " = " << std::atanh(z3) << '\n'
              << "atan" << z3 * i << " / i = " << std::atan(z3 * i) / i
   << '\n';
}

⭐ Output ⭐

atanh(2.000000,0.000000) = (0.549306,1.570796)
atanh(2.000000,-0.000000) (the other side of the cut) =
(0.549306,-1.570796)
atanh(1.000000,2.000000) = (0.173287,1.178097)
atan(-2.000000,1.000000) / i = (0.173287,1.178097)

---

💜 See also 💜

• asinh(std::complex) — computes area hyperbolic sine of a complex number (C++11) — arsinh(z) — function template
• acosh(std::complex) — computes area hyperbolic cosine of a complex number (C++11) — arcosh(z) — function template
• tanh(std::complex) — computes hyperbolic tangent of a complex number — tanh(z) — function template
• atanh, atanhf, atanhl (C++11) — computes the inverse hyperbolic tangent — artanh(x) — function
• C documentation for catanh — for when you wanna hang out in C land 🍓

---

Okay that's the whole page, no gatekeeping, no cap. Now go forth and compute your arc hyperbolic tangents, but like, correctly. 🫶

---

Sign-off time, bestie: this little masterpiece came from http://cppreference.com, dated 2024.06.10, and it's the std::atanh(std::complex)(3) page. Periodt. 🔥