std::tanh(std::complex)(3)

💖 std::tanh(std::complex) — NAME 💖

okay so bestie, welcome to the glow-up era of std::tanh(std::complex) — yes, the name is literally just std::tanh(std::complex), no notes, it's giving "I contain multitudes" but the multitudes are complex hyperbolic tangent. We're in the C++ Standard Library manual, section (3), and honestly? Buckle up, this one's got ✨*math*✨.

---

✨ Synopsis ✨

first things first, this whole vibe lives in the header <complex>:

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

and what does it do? it computes the complex hyperbolic tangent of a complex value z. that's it, that's the whole thing, and it ate 💅

---

🎀 Parameters 🎀

• z — a complex value. that's the whole parameter list bestie, one (1) value, and it's complex. iconic.

---

🔥 Return value 🔥

if nothing goes wrong, you get the complex hyperbolic tangent of z back. no cap, that's the deal 🫶

🌸 Error handling and special values 🌸

errors get reported consistent with math_errhandling.

and if the implementation supports IEEE floating-point arithmetic, here's the whole special-values saga, and yes there are eleven of them, we're not skipping a single one:

• std::tanh(std::conj(z)) == std::conj(std::tanh(z)).
• std::tanh(-z) == -std::tanh(z).
• if z is (+0,+0), the result is (+0,+0).
• if z is (x,+∞) (for any^[1] finite x), the result is (NaN,NaN) and FE_INVALID is raised.
• if z is (x,NaN) (for any^[2] finite x), the result is (NaN,NaN) and FE_INVALID may be raised.
• if z is (+∞,y) (for any finite positive y), the result is (1,+0).
• if z is (+∞,+∞), the result is (1,±0) (the sign of the imaginary part is unspecified).
• if z is (+∞,NaN), the result is (1,±0) (the sign of the imaginary part is unspecified).
• if z is (NaN,+0), the result is (NaN,+0).
• if z is (NaN,y) (for any non-zero y), the result is (NaN,NaN) and FE_INVALID may be raised.
• if z is (NaN,NaN), the result is (NaN,NaN).

little footnote moment, don't skip these 👀 1. ↑ per C11 DR471, this only holds for non-zero x. If z is (0,∞), the result should be (0,NaN). 2. ↑ per C11 DR471, this only holds for non-zero x. If z is (0,NaN), the result should be (0,NaN).

---

🦋 Notes 🦋

the mathematical definition of hyperbolic tangent is lowkey gorgeous:

tanh z = ( e^z - e^-z ) / ( e^z + e^-z )

hyperbolic tangent is an analytical function on the complex plane and has no branch cuts. it's periodic with respect to the imaginary component, with period πi, and it has poles of the first order along the imaginary line, at coordinates (0, π(1/2 + n)). however — and this is the plot twist — no common floating-point representation is able to represent π/2 exactly, so there is literally no value of the argument for which a pole error occurs. we love a problem that solves itself 😭

---

💜 Example 💜

// Run this code

#include <cmath>
#include <complex>
#include <iostream>

int main()
{
    std::cout << std::fixed;
    std::complex<double> z(1.0, 0.0); // behaves like real tanh along the real line
    std::cout << "tanh" << z << " = " << std::tanh(z)
              << " (tanh(1) = " << std::tanh(1) << ")\n";

    std::complex<double> z2(0.0, 1.0); // behaves like tangent along the imaginary line
    std::cout << "tanh" << z2 << " = " << std::tanh(z2)
              << " ( tan(1) = " << std::tan(1) << ")\n";
}

⭐ Output ⭐

tanh(1.000000,0.000000) = (0.761594,0.000000) (tanh(1) = 0.761594)
tanh(0.000000,1.000000) = (0.000000,1.557408) ( tan(1) = 1.557408)

---

🌈 See also 🌈

• sinh(std::complex) — computes hyperbolic sine of a complex number (({\small\sinh{z}})sinh(z)) (function template)
• cosh(std::complex) — computes hyperbolic cosine of a complex number (({\small\cosh{z}})cosh(z)) (function template)
• atanh(std::complex) (C++11) — computes area hyperbolic tangent of a complex number (({\small\operatorname{artanh}{z}})artanh(z)) (function template)
• tanh, tanhf, tanhl (C++11), (C++11) — computes hyperbolic tangent (({\small\tanh{x}})tanh(x)) (function)
• tanh(std::valarray) — applies the function std::tanh to each element of valarray (function template)
• C documentation for ctanh — go read the C one if you're feeling multilingual 🧚

---

okay that's the whole page bestie, you're officially a complex-hyperbolic-tangent expert, no cap 🎀✨

source: http://cppreference.com · date: 2024.06.10 · from the std::tanh(std::complex)(3) page — go forth and tanh responsibly 💅👑