Add inverse hyperbolic functions `asinh()`, `acosh()` & `atanh()`

GDScript has the following built-in trigonometry functions:

- `sin()`
- `cos()`
- `tan()`
- `asin()`
- `acos()`
- `atan()`
- `atan()`
- `sinh()`
- `cosh()`
- `tanh()`

However, it lacks the hyperbolic arc (also known as inverse
hyperbolic) functions:

- `asinh()`
- `acosh()`
- `atanh()`

Implement them by just exposing the C++ Math library, but clamping
its values to the closest real defined value.
For the cosine, clamp input values lower than 1 to 1.
In the case of the tangent, where the limit value is infinite,
clamp it to -inf or +inf.

References #78377
Fixes godotengine/godot-proposals#7110

1 files changed, 11 insertions, 0 deletions

diff --git a/core/math/math_funcs.h b/core/math/math_funcs.h
index f96d3a909f..934c75b5d3 100644
--- a/core/math/math_funcs.h
+++ b/core/math/math_funcs.h
@@ -88,6 +88,17 @@ public:
 	static _ALWAYS_INLINE_ double atan2(double p_y, double p_x) { return ::atan2(p_y, p_x); }
 	static _ALWAYS_INLINE_ float atan2(float p_y, float p_x) { return ::atan2f(p_y, p_x); }
 
+	static _ALWAYS_INLINE_ double asinh(double p_x) { return ::asinh(p_x); }
+	static _ALWAYS_INLINE_ float asinh(float p_x) { return ::asinhf(p_x); }
+
+	// Always does clamping so always safe to use.
+	static _ALWAYS_INLINE_ double acosh(double p_x) { return p_x < 1 ? 0 : ::acosh(p_x); }
+	static _ALWAYS_INLINE_ float acosh(float p_x) { return p_x < 1 ? 0 : ::acoshf(p_x); }
+
+	// Always does clamping so always safe to use.
+	static _ALWAYS_INLINE_ double atanh(double p_x) { return p_x <= -1 ? -INFINITY : (p_x >= 1 ? INFINITY : ::atanh(p_x)); }
+	static _ALWAYS_INLINE_ float atanh(float p_x) { return p_x <= -1 ? -INFINITY : (p_x >= 1 ? INFINITY : ::atanhf(p_x)); }
+
 	static _ALWAYS_INLINE_ double sqrt(double p_x) { return ::sqrt(p_x); }
 	static _ALWAYS_INLINE_ float sqrt(float p_x) { return ::sqrtf(p_x); }