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

[jynus]

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 closes 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

[jynus]

Aside from me being super clumsy with the syntax (working on it) I am not super-sure about the clamping to infinity- want to see what people think and will update docs to reflect those special cases if agreed.

[kleonc]

cc @lawnjelly Any thoughts on clamping atanh(x) to infinities part? (see godotengine/godot-proposals#7110 (comment) and following comments)

[lawnjelly]

cc @lawnjelly Any thoughts on clamping atanh(x) to infinities part? (see godotengine/godot-proposals#7110 (comment) and following comments)

I don't think I've used it, but yes clamping result to INFINITY does seem preferable to NaN, as with the other safe math functions.

[jynus]

This is what it now would say on acosh:

Returns the hyperbolic arc (also called inverse) cosine of x, returning a value in radians. Use it to get the angle from an angle's cosine in hyperbolic space if x is larger or equal to 1. For values of x lower than 1, it will return 0, in order to prevent acosh from returning @GDScript.NAN.

var a = acosh(2) # Returns 1.31695789692482
cosh(a) # Returns 2

var b = acosh(-1) # Returns 0

For atanh:

Returns the hyperbolic arc (also called inverse) tangent of x, returning a value in radians. Use it to get the angle from an angle's tangent in hyperbolic space if x is between -1 and 1 (non-inclusive).

In mathematics, the inverse hyperbolic tangent is only defined for -1 < x < 1 in the real set, so values equal or lower to -1 for x return negative @GDScript.INF and values equal or higher than 1 return positive @GDScript.INF in order to prevent atanh from returning @GDScript.NAN.

var a = atanh(0.9) # Returns 1.47221948958322
tanh(a) # Returns 0.9

var b = atanh(-2) # Returns -inf
tanh(b) # Returns -1

I've also added checks of infinity sign in tests.

[AThousandShips]

LGTM

[kleonc]

Needs a rebase/update after #78108.

[jynus]

I rebased to head. Let's see if that works, as I was getting some errors on HEAD before the patch applied - it was giving me some unit testing errors unrelated to the Math module.

[jynus]

The errors I got were wrong compiling flags I was using. Unit tests for the new functionality (and the rest) still work normally after manual rebase @kleonc

[akien-mga]

Thanks!