lua_std/

math.rs

//! The mathematical library.
//!
//! Provides basic mathematical functions and the interface to the
//! integer/float subtypes of [`number`]. Functions annotated
//! "integer/float" give integer results for integer arguments and float
//! results otherwise.
use crate::{boolean, number, option, string, Repeatable};

/// A value larger than any other numerical value: the float infinity,
/// `HUGE_VAL`.
///
/// # Examples
///
/// ```lua
/// print(math.huge)      --> inf
/// print(-math.huge)     --> -inf
/// print(1 / 0)          --> inf
/// ```
///
/// # See also
///
/// [`maxinteger`], [`mininteger`]
pub const huge: number = number;

/// An integer with the maximum value for an integer:
/// 9223372036854775807 (2⁶³ − 1).
///
/// # Examples
///
/// ```lua
/// print(math.maxinteger)      --> 9223372036854775807
/// print(math.maxinteger + 1 == math.mininteger)  --> true (wraps around)
/// ```
///
/// # See also
///
/// [`mininteger`], [`huge`]
pub const maxinteger: number = number;

/// An integer with the minimum value for an integer:
/// −9223372036854775808 (−2⁶³).
///
/// # Examples
///
/// ```lua
/// print(math.mininteger)      --> -9223372036854775808
/// ```
///
/// # See also
///
/// [`maxinteger`], [`huge`]
pub const mininteger: number = number;

/// The value of π.
///
/// # Examples
///
/// ```lua
/// print(math.pi)              --> 3.141592653589793
/// print(math.deg(math.pi))    --> 180.0
/// ```
///
/// # See also
///
/// [`deg`], [`rad`]
pub const pi: number = number;

/// Returns the absolute value of a number (integer/float).
///
/// # Parameters
///
/// - **`x`**: a number.
///
/// # Return value
///
/// The maximum value between `x` and −`x`. The subtype of the result
/// matches the subtype of the argument.
///
/// # Examples
///
/// ```lua
/// print(math.abs(-5))      --> 5
/// print(math.abs(-5.25))   --> 5.25
/// print(math.abs(7))       --> 7
/// ```
pub fn abs(x: number) -> number {
    todo!()
}

/// Returns the arc cosine of a number, in radians.
///
/// # Parameters
///
/// - **`x`**: a number in the range \[−1, 1].
///
/// # Return value
///
/// The arc cosine of `x`, in radians, as a float in the range
/// \[0, π]. Arguments outside \[−1, 1] produce NaN.
///
/// # Examples
///
/// ```lua
/// print(math.acos(1))     --> 0.0
/// print(math.acos(0))     --> 1.5707963267948966
/// print(math.acos(-1))    --> 3.141592653589793
/// ```
///
/// # See also
///
/// [`asin`], [`atan`], [`cos`]
pub fn acos(x: number) -> number {
    todo!()
}

/// Returns the arc sine of a number, in radians.
///
/// # Parameters
///
/// - **`x`**: a number in the range \[−1, 1].
///
/// # Return value
///
/// The arc sine of `x`, in radians, as a float in the range
/// \[−π/2, π/2]. Arguments outside \[−1, 1] produce NaN.
///
/// # Examples
///
/// ```lua
/// print(math.asin(0))     --> 0.0
/// print(math.asin(1))     --> 1.5707963267948966
/// ```
///
/// # See also
///
/// [`acos`], [`atan`], [`sin`]
pub fn asin(x: number) -> number {
    todo!()
}

/// Returns the arc tangent of `y/x`, in radians.
///
/// # Parameters
///
/// - **`y`**: a number.
/// - **`x`**: a number (default 1).
///
/// # Return value
///
/// The arc tangent of `y/x`, in radians, as a float. The signs of
/// both arguments are used to find the quadrant of the result, and
/// the function handles the case of `x` being zero correctly.
///
/// # Examples
///
/// ```lua
/// print(math.atan(1))        --> 0.7853981633974483  (π/4)
/// print(math.atan(1, 0))     --> 1.5707963267948966  (π/2)
/// print(math.atan(-1, -1))   --> -2.35619449019234545  (third quadrant)
/// ```
///
/// # See also
///
/// [`acos`], [`asin`], [`tan`]
pub fn atan(y: number, x: option<number>) -> number {
    todo!()
}

/// Rounds a number up to the nearest integer.
///
/// # Parameters
///
/// - **`x`**: a number.
///
/// # Return value
///
/// The smallest integral value greater than or equal to `x`, as an
/// integer. Raises an error if the result does not fit in an integer.
///
/// # Examples
///
/// ```lua
/// print(math.ceil(4.2))    --> 5
/// print(math.ceil(-4.2))   --> -4
/// print(math.ceil(7))      --> 7
/// ```
///
/// # See also
///
/// [`floor`], [`modf`]
pub fn ceil(x: number) -> number {
    todo!()
}

/// Returns the cosine of a number given in radians.
///
/// # Parameters
///
/// - **`x`**: an angle in radians.
///
/// # Return value
///
/// The cosine of `x`, as a float in the range \[−1, 1].
///
/// # Examples
///
/// ```lua
/// print(math.cos(0))          --> 1.0
/// print(math.cos(math.pi))    --> -1.0
/// ```
///
/// # See also
///
/// [`sin`], [`tan`], [`acos`], [`rad`]
pub fn cos(x: number) -> number {
    todo!()
}

/// Converts an angle from radians to degrees.
///
/// # Parameters
///
/// - **`x`**: an angle in radians.
///
/// # Return value
///
/// The angle `x` expressed in degrees, as a float.
///
/// # Examples
///
/// ```lua
/// print(math.deg(math.pi))       --> 180.0
/// print(math.deg(math.pi / 2))   --> 90.0
/// ```
///
/// # See also
///
/// [`rad`], [`pi`]
pub fn deg(x: number) -> number {
    todo!()
}

/// Returns *e* raised to a power.
///
/// # Parameters
///
/// - **`x`**: a number.
///
/// # Return value
///
/// The value *eˣ*, as a float, where *e* is the base of natural
/// logarithms.
///
/// # Examples
///
/// ```lua
/// print(math.exp(0))    --> 1.0
/// print(math.exp(1))    --> 2.718281828459045
/// ```
///
/// # See also
///
/// [`log`]
pub fn exp(x: number) -> number {
    todo!()
}

/// Rounds a number down to the nearest integer.
///
/// # Parameters
///
/// - **`x`**: a number.
///
/// # Return value
///
/// The largest integral value less than or equal to `x`, as an
/// integer. Raises an error if the result does not fit in an integer.
///
/// # Examples
///
/// ```lua
/// print(math.floor(4.7))    --> 4
/// print(math.floor(-4.7))   --> -5
/// print(math.floor(7))      --> 7
/// ```
///
/// # See also
///
/// [`ceil`], [`modf`], [`tointeger`]
pub fn floor(x: number) -> number {
    todo!()
}

/// Splits a number into a normalized fraction and an exponent.
/// **Re-added in Lua 5.5** (it had been removed in 5.3).
///
/// # Parameters
///
/// - **`x`**: a number.
///
/// # Return value
///
/// Two values `m` and `e` such that `x == m * 2^e`, where `e` is an
/// integer and the absolute value of `m` is in the range [0.5, 1) —
/// or zero when `x` is zero.
///
/// # Examples
///
/// ```lua
/// print(math.frexp(8))      --> 0.5   4
/// print(math.frexp(1))      --> 0.5   1
/// print(math.frexp(0))      --> 0.0   0
/// ```
///
/// # See also
///
/// [`ldexp`]
pub fn frexp(x: number) -> (number, number) {
    todo!()
}

/// Builds a float from a mantissa and an exponent.
/// **Re-added in Lua 5.5** (it had been removed in 5.3).
///
/// # Parameters
///
/// - **`m`**: the mantissa.
/// - **`e`**: an integer exponent.
///
/// # Return value
///
/// The float `m * 2^e`.
///
/// # Examples
///
/// ```lua
/// print(math.ldexp(0.5, 4))    --> 8.0
/// print(math.ldexp(1, 10))     --> 1024.0
/// ```
///
/// # See also
///
/// [`frexp`]
pub fn ldexp(m: number, e: number) -> number {
    todo!()
}

/// Returns the remainder of a division, rounding the quotient towards
/// zero (integer/float).
///
/// # Parameters
///
/// - **`x`**: the dividend.
/// - **`y`**: the divisor.
///
/// # Return value
///
/// The remainder of `x / y` with the sign of `x`. Note that the `%`
/// operator behaves differently: it rounds the quotient towards minus
/// infinity, so the result takes the sign of the divisor.
///
/// # Examples
///
/// ```lua
/// print(math.fmod(7, 3))     --> 1
/// print(math.fmod(-7, 3))    --> -1
/// print(-7 % 3)              --> 2   (the operator rounds differently)
/// ```
pub fn fmod(x: number, y: number) -> number {
    todo!()
}

/// Returns the logarithm of a number in a given base.
///
/// # Parameters
///
/// - **`x`**: a positive number.
/// - **`base`**: the logarithm base (default *e*).
///
/// # Return value
///
/// The logarithm of `x` in the given base, as a float. Without
/// `base`, returns the natural logarithm of `x`.
///
/// # Examples
///
/// ```lua
/// print(math.log(math.exp(1)))   --> 1.0
/// print(math.log(8, 2))          --> 3.0
/// print(math.log(100, 10))       --> 2.0
/// ```
///
/// # See also
///
/// [`exp`]
pub fn log(x: number, base: option<number>) -> number {
    todo!()
}

/// Returns the largest of its arguments.
///
/// # Parameters
///
/// - **`x, ···`**: one or more numbers.
///
/// # Return value
///
/// The argument with the maximum value, according to the `<`
/// operator.
///
/// # Examples
///
/// ```lua
/// print(math.max(1, 5, 3))     --> 5
/// print(math.max(-1, -5))      --> -1
/// ```
///
/// # See also
///
/// [`min`]
pub fn max(values: Repeatable<number>) -> number {
    todo!()
}

/// Returns the smallest of its arguments.
///
/// # Parameters
///
/// - **`x, ···`**: one or more numbers.
///
/// # Return value
///
/// The argument with the minimum value, according to the `<`
/// operator.
///
/// # Examples
///
/// ```lua
/// print(math.min(1, 5, 3))     --> 1
/// print(math.min(-1, -5))      --> -5
/// ```
///
/// # See also
///
/// [`max`]
pub fn min(values: Repeatable<number>) -> number {
    todo!()
}

/// Splits a number into its integral and fractional parts.
///
/// # Parameters
///
/// - **`x`**: a number.
///
/// # Return value
///
/// Two values: the integral part of `x` and the fractional part of
/// `x`. Its second result is always a float.
///
/// # Examples
///
/// ```lua
/// print(math.modf(3.7))     --> 3.0   0.7000000000000002
/// print(math.modf(-3.7))    --> -3.0  -0.7000000000000002
/// ```
///
/// # See also
///
/// [`floor`], [`ceil`], [`fmod`]
pub fn modf(x: number) -> (number, number) {
    todo!()
}

/// Converts an angle from degrees to radians.
///
/// # Parameters
///
/// - **`x`**: an angle in degrees.
///
/// # Return value
///
/// The angle `x` expressed in radians, as a float.
///
/// # Examples
///
/// ```lua
/// print(math.rad(180))    --> 3.141592653589793
/// print(math.rad(90))     --> 1.5707963267948966
/// ```
///
/// # See also
///
/// [`deg`], [`pi`]
pub fn rad(x: number) -> number {
    todo!()
}

/// Returns a pseudo-random number.
///
/// # Parameters
///
/// - **`m`**: an integer, the lower bound (or the upper bound of the
///   range \[1, m], when `n` is absent).
/// - **`n`**: an integer, the upper bound.
///
/// # Return value
///
/// With no arguments, a pseudo-random float with uniform distribution
/// in the range \[0, 1). With one or two integer arguments, a
/// pseudo-random integer with uniform distribution in the range
/// \[1, m] or \[m, n], respectively.
///
/// # Examples
///
/// ```lua
/// print(math.random())        --> 0.2896938390679077  (some float in [0, 1))
/// print(math.random(6))       --> 4                 (a die roll: 1..6)
/// print(math.random(10, 20))  --> 17                (an integer in 10..20)
/// ```
///
/// # See also
///
/// [`randomseed`]
pub fn random(m: option<number>, n: option<number>) -> number {
    todo!()
}

/// Initialises the pseudo-random number generator.
///
/// # Parameters
///
/// - **`x`**: an integer used as seed.
/// - **`y`**: an integer used as a second seed component.
///
/// # Return value
///
/// The two integer components of the seed that was set, so they can
/// be reused later to repeat the sequence.
///
/// # Description
///
/// Equal seeds produce equal sequences of numbers. When called with
/// no arguments, Lua generates a seed with a weak attempt for
/// randomness. (Since Lua the generator is seeded automatically at
/// startup, so calling this function is only needed to reproduce a
/// sequence.)
///
/// # Examples
///
/// ```lua
/// math.randomseed(42)
/// print(math.random(100))   --> always the same value for seed 42
/// ```
///
/// # See also
///
/// [`random`]
pub fn randomseed(x: option<number>, y: option<number>) -> (number, number) {
    todo!()
}

/// Returns the sine of a number given in radians.
///
/// # Parameters
///
/// - **`x`**: an angle in radians.
///
/// # Return value
///
/// The sine of `x`, as a float in the range \[−1, 1].
///
/// # Examples
///
/// ```lua
/// print(math.sin(0))              --> 0.0
/// print(math.sin(math.pi / 2))    --> 1.0
/// ```
///
/// # See also
///
/// [`cos`], [`tan`], [`asin`], [`rad`]
pub fn sin(x: number) -> number {
    todo!()
}

/// Returns the square root of a number.
///
/// # Parameters
///
/// - **`x`**: a number greater than or equal to 0.
///
/// # Return value
///
/// The square root of `x`, as a nonnegative float. If `x` is less
/// than 0, the result is NaN.
///
/// # Description
///
/// You can also use the expression `x^0.5` to compute this value.
/// Like all Lua functions, `sqrt` lives in a table (the `math`
/// library), so it is called as `math.sqrt(x)`.
///
/// # Examples
///
/// ```lua
/// print(math.sqrt(0))          --> 0.0
/// print(math.sqrt(1))          --> 1.0
/// print(math.sqrt(2))          --> 1.4142135623730951
/// print(math.sqrt(9))          --> 3.0
/// print(math.sqrt(16))         --> 4.0
/// print(math.sqrt(-1))         --> nan
/// print(math.sqrt(math.huge))  --> inf
/// ```
///
/// # See also
///
/// [`exp`], [`log`]
pub fn sqrt(x: number) -> number {
    todo!()
}

/// Returns the tangent of a number given in radians.
///
/// # Parameters
///
/// - **`x`**: an angle in radians.
///
/// # Return value
///
/// The tangent of `x`, as a float.
///
/// # Examples
///
/// ```lua
/// print(math.tan(0))              --> 0.0
/// print(math.tan(math.pi / 4))    --> 0.9999999999999999  (float rounding)
/// ```
///
/// # See also
///
/// [`sin`], [`cos`], [`atan`]
pub fn tan(x: number) -> number {
    todo!()
}

/// Converts a value to an integer, if possible.
///
/// # Parameters
///
/// - **`x`**: any value.
///
/// # Return value
///
/// If `x` is convertible to an integer (an integer, a float with an
/// integral value that fits, or a string that reads as one), returns
/// that integer; otherwise, returns `nil`.
///
/// # Examples
///
/// ```lua
/// print(math.tointeger(3.0))    --> 3
/// print(math.tointeger(3.5))    --> nil
/// print(math.tointeger("42"))   --> 42
/// ```
///
/// # See also
///
/// [`floor`], `math.type`
pub fn tointeger(x: number) -> option<number> {
    todo!()
}

/// Reveals the subtype of a number.
///
/// # Parameters
///
/// - **`x`**: any value.
///
/// # Return value
///
/// The string `"integer"` if `x` is an integer, `"float"` if it is a
/// float, or `nil` if `x` is not a number.
///
/// # Examples
///
/// ```lua
/// print(math.type(3))      --> integer
/// print(math.type(3.0))    --> float
/// print(math.type("3"))    --> nil
/// ```
///
/// # See also
///
/// [`tointeger`], [`type`](crate::type())
pub fn r#type(x: number) -> option<string> {
    todo!()
}

/// Compares two integers as unsigned values.
///
/// # Parameters
///
/// - **`m`**: an integer.
/// - **`n`**: an integer.
///
/// # Return value
///
/// A boolean: true if and only if `m` is below `n` when they are
/// compared as unsigned integers.
///
/// # Examples
///
/// ```lua
/// print(math.ult(1, 2))     --> true
/// print(math.ult(-1, 2))    --> false  (-1 is huge as unsigned)
/// ```
pub fn ult(m: number, n: number) -> boolean {
    todo!()
}

/// Rounds a number to the nearest integer, halves away from zero.
/// **Extended library — feature `extended`** (from `extended.lua`).
///
/// # Parameters
///
/// - **`ndigits`**: round to this many decimal places instead; the
///   result is then a float.
///
/// # Examples
///
/// ```lua
/// print(math.round(2.5))          --> 3
/// print(math.round(-2.5))         --> -3
/// print(math.round(2.4))          --> 2
/// print(math.round(3.14159, 2))   --> 3.14
/// ```
///
/// # See also
///
/// [`floor`], [`ceil`]
#[cfg(feature = "extended")]
pub fn round(x: number, ndigits: option<number>) -> number {
    todo!()
}

/// Restricts a number to a range.
/// **Extended library — feature `extended`** (from `extended.lua`).
/// From Rust `f64::clamp`.
///
/// # Examples
///
/// ```lua
/// print(math.clamp(5, 1, 3))     --> 3
/// print(math.clamp(-5, 1, 3))    --> 1
/// print(math.clamp(2, 1, 3))     --> 2
/// ```
///
/// # See also
///
/// [`min`], [`max`]
#[cfg(feature = "extended")]
pub fn clamp(x: number, min: number, max: number) -> number {
    todo!()
}

/// Returns the sign of a number: 1, −1 or 0. NaN is returned
/// unchanged.
/// **Extended library — feature `extended`** (from `extended.lua`).
/// From Rust `f64::signum`.
///
/// # Examples
///
/// ```lua
/// print(math.sign(9))       --> 1
/// print(math.sign(-0.5))    --> -1
/// print(math.sign(0))       --> 0
/// ```
///
/// # See also
///
/// [`abs`]
#[cfg(feature = "extended")]
pub fn sign(x: number) -> number {
    todo!()
}