math.acos() - Lua | Version 5.4 Docs

The math.acos() function in lua returns the inverse cosine (in radians) of a number. That is:

∀ x ∊ [-1, 1], math.acos(x) = arccos(x) = the unique y ∊ [0, π] such that cos(y) = x.

Syntax

math.acos(x)

Parameters

x
A number between -1 and 1 (inclusive), representing the cosine value of an angle.

Return value

The inverse cosine of x, expressed as an angle in radians between 0 and π (inclusive). If x is less than -1 or greater than 1, the function returns nil or may trigger an error, as the value is undefined in these cases.

Description

Because math.acos() is a static function, it is always used as math.acos(), rather than as a method of a lua object. This function is typically used to compute the angle corresponding to a given cosine value.

Examples

Using `math.acos()`

print(math.acos(-1))       -- 3.1415926535898 (π)
print(math.acos(0))        -- 1.5707963267949 (π/2)
print(math.acos(0.5))      -- 1.0471975511966 (about π/3)
print(math.acos(1))        -- 0

Handling out-of-range values

If the input value is outside the range [-1, 1], the result is undefined, and an error or nil may occur.

-- Correct usage:
print(math.acos(0.75))     -- A valid angle in radians

-- Incorrect usage:
-- print(math.acos(2))     -- Error: argument out of range