MathUtils 1.0.1

//! # MathUtils
//!
//! A high-fidelity, zero-dependency Rust crate that mirrors JavaScript's ECMAScript `Math` built-in object.
//!
//! `MathUtils` provides the exact constants, methods, rounding semantics, and edge-case behaviors
//! specified by the ECMAScript 2024 language specification, with dual support for JavaScript-style
//! naming (`Math::clz32`, `Math::PI`, `Math::sumPrecise`) and idiomatic Rust conventions.
//!
//! ## Quick Start
//!
//! ```rust
//! use MathUtils::Math;
//!
//! // Exact ECMAScript rounding behavior:
//! assert_eq!(Math::round(-0.5), -0.0);
//! assert!(Math::round(-0.5).is_sign_negative());
//! assert_eq!(Math::round(1.5), 2.0);
//! assert_eq!(Math::round(-1.5), -1.0);
//!
//! // Full trigonometric and logarithmic methods:
//! assert_eq!(Math::sin(0.0), 0.0);
//! assert_eq!(Math::log10(100.0), 2.0);
//! assert_eq!(Math::imul(-1, 8), -8);
//!
//! // IEEE 754 float precision conversions:
//! assert_eq!(Math::fround(1.337), 1.3370000123977661);
//! assert_eq!(Math::f16round(std::f64::consts::PI), 3.140625);
//!
//! // Variadic helpers and macros:
//! use MathUtils::math_max;
//! assert_eq!(math_max!(1.0, 99.5, -42.0), 99.5);
//! ```

#![allow(non_snake_case)]

pub mod constants;
pub mod conversions;
mod f16;
pub mod macros;
mod random;
mod sum_precise;

pub use constants::*;
pub use conversions::{ToJsInt32, ToJsUint32};

/// The primary namespace mirroring JavaScript's built-in `Math` object.
///
/// Contains all standard constants and methods.
pub struct Math;

impl Math {
    // -------------------------------------------------------------------------
    // Constants
    // -------------------------------------------------------------------------

    /// Euler's constant ($e$), the base of natural logarithms ($\approx 2.718281828459045$).
    ///
    /// Mirrors JavaScript's `Math.E`.
    pub const E: f64 = constants::E;

    /// Natural logarithm of 10 ($\approx 2.302585092994046$).
    ///
    /// Mirrors JavaScript's `Math.LN10`.
    pub const LN10: f64 = constants::LN10;
    /// Snake-case alias for [`Math::LN10`].
    pub const LN_10: f64 = constants::LN_10;

    /// Natural logarithm of 2 ($\approx 0.6931471805599453$).
    ///
    /// Mirrors JavaScript's `Math.LN2`.
    pub const LN2: f64 = constants::LN2;
    /// Snake-case alias for [`Math::LN2`].
    pub const LN_2: f64 = constants::LN_2;

    /// Base-10 logarithm of Euler's constant $e$ ($\approx 0.4342944819032518$).
    ///
    /// Mirrors JavaScript's `Math.LOG10E`.
    pub const LOG10E: f64 = constants::LOG10E;
    /// Snake-case alias for [`Math::LOG10E`].
    pub const LOG10_E: f64 = constants::LOG10_E;

    /// Base-2 logarithm of Euler's constant $e$ ($\approx 1.4426950408889634$).
    ///
    /// Mirrors JavaScript's `Math.LOG2E`.
    pub const LOG2E: f64 = constants::LOG2E;
    /// Snake-case alias for [`Math::LOG2E`].
    pub const LOG2_E: f64 = constants::LOG2_E;

    /// Archimedes' constant ($\pi$), the ratio of a circle's circumference to its diameter ($\approx 3.141592653589793$).
    ///
    /// Mirrors JavaScript's `Math.PI`.
    pub const PI: f64 = constants::PI;

    /// Square root of 1/2 ($\approx 0.7071067811865476$).
    ///
    /// Mirrors JavaScript's `Math.SQRT1_2`.
    pub const SQRT1_2: f64 = constants::SQRT1_2;
    /// Snake-case alias for [`Math::SQRT1_2`].
    pub const SQRT_1_2: f64 = constants::SQRT_1_2;

    /// Square root of 2 ($\approx 1.4142135623730951$).
    ///
    /// Mirrors JavaScript's `Math.SQRT2`.
    pub const SQRT2: f64 = constants::SQRT2;
    /// Snake-case alias for [`Math::SQRT2`].
    pub const SQRT_2: f64 = constants::SQRT_2;

    // -------------------------------------------------------------------------
    // Functions
    // -------------------------------------------------------------------------

    /// Computes the absolute value (magnitude) of a number $|x|$.
    ///
    /// Returns the positive value of `x` regardless of its sign.
    ///
    /// Mirrors JavaScript's `Math.abs(x)`.
    ///
    /// # Special Values
    /// - If `x` is `NaN`, returns `NaN`.
    /// - If `x` is `-0.0`, returns `+0.0`.
    /// - If `x` is `-Infinity`, returns `+Infinity`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::abs(5.0), 5.0);
    /// assert_eq!(Math::abs(-5.0), 5.0);
    /// assert_eq!(Math::abs(-0.0), 0.0);
    /// assert!(Math::abs(-0.0).is_sign_positive());
    /// assert_eq!(Math::abs(-f64::INFINITY), f64::INFINITY);
    /// assert!(Math::abs(f64::NAN).is_nan());
    /// ```
    #[inline]
    pub fn abs(x: f64) -> f64 {
        x.abs()
    }

    /// Computes the principal value of the arc cosine (inverse cosine) of `x`, in radians.
    ///
    /// Returns an angle $\theta \in [0, \pi]$ such that $\cos(\theta) = x$.
    ///
    /// Mirrors JavaScript's `Math.acos(x)`.
    ///
    /// # Domain & Special Values
    /// - Defined for $x \in [-1.0, 1.0]$.
    /// - For $x < -1.0$ or $x > 1.0$, returns `NaN`.
    /// - If `x` is `1.0`, returns `0.0`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::acos(1.0), 0.0);
    /// assert!((Math::acos(0.0) - Math::PI / 2.0).abs() < 1e-15);
    /// assert!((Math::acos(-1.0) - Math::PI).abs() < 1e-15);
    /// assert!(Math::acos(2.0).is_nan());
    /// ```
    #[inline]
    pub fn acos(x: f64) -> f64 {
        x.acos()
    }

    /// Computes the inverse hyperbolic cosine ($\operatorname{arcosh}$) of `x`.
    ///
    /// Mathematically defined as $\operatorname{acosh}(x) = \ln(x + \sqrt{x^2 - 1})$.
    ///
    /// Mirrors JavaScript's `Math.acosh(x)`.
    ///
    /// # Domain & Special Values
    /// - Defined for $x \in [1.0, +\infty)$.
    /// - For $x < 1.0$, returns `NaN`.
    /// - If `x` is `1.0`, returns `0.0`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::acosh(1.0), 0.0);
    /// assert_eq!(Math::acosh(2.0), 1.3169578969248166);
    /// assert!(Math::acosh(0.5).is_nan());
    /// assert_eq!(Math::acosh(f64::INFINITY), f64::INFINITY);
    /// ```
    #[inline]
    pub fn acosh(x: f64) -> f64 {
        x.acosh()
    }

    /// Computes the principal value of the arc sine (inverse sine) of `x`, in radians.
    ///
    /// Returns an angle $\theta \in [-\pi/2, \pi/2]$ such that $\sin(\theta) = x$.
    ///
    /// Mirrors JavaScript's `Math.asin(x)`.
    ///
    /// # Domain & Special Values
    /// - Defined for $x \in [-1.0, 1.0]$.
    /// - For $|x| > 1.0$, returns `NaN`.
    /// - Preserves negative zero (`Math::asin(-0.0) == -0.0`).
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::asin(0.0), 0.0);
    /// assert!((Math::asin(1.0) - Math::PI / 2.0).abs() < 1e-15);
    /// assert!((Math::asin(-1.0) - (-Math::PI / 2.0)).abs() < 1e-15);
    /// assert!(Math::asin(1.5).is_nan());
    /// ```
    #[inline]
    pub fn asin(x: f64) -> f64 {
        x.asin()
    }

    /// Computes the inverse hyperbolic sine ($\operatorname{arsinh}$) of `x`.
    ///
    /// Mathematically defined as $\operatorname{asinh}(x) = \ln(x + \sqrt{x^2 + 1})$.
    ///
    /// Mirrors JavaScript's `Math.asinh(x)`.
    ///
    /// # Special Values
    /// - Defined for all real numbers $x \in (-\infty, +\infty)$.
    /// - Preserves negative zero (`Math::asinh(-0.0) == -0.0`).
    /// - If `x` is $\pm\infty$, returns $\pm\infty$.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::asinh(0.0), 0.0);
    /// assert_eq!(Math::asinh(1.0), 0.881373587019543);
    /// assert_eq!(Math::asinh(-1.0), -0.881373587019543);
    /// ```
    #[inline]
    pub fn asinh(x: f64) -> f64 {
        x.asinh()
    }

    /// Computes the principal value of the arc tangent (inverse tangent) of `x`, in radians.
    ///
    /// Returns an angle $\theta \in (-\pi/2, \pi/2)$ such that $\tan(\theta) = x$.
    ///
    /// Mirrors JavaScript's `Math.atan(x)`.
    ///
    /// # Special Values
    /// - Defined for all real numbers $x \in (-\infty, +\infty)$.
    /// - If `x` is `+Infinity`, returns $+\pi/2$.
    /// - If `x` is `-Infinity`, returns $-\pi/2$.
    /// - Preserves negative zero (`Math::atan(-0.0) == -0.0`).
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::atan(0.0), 0.0);
    /// assert!((Math::atan(1.0) - Math::PI / 4.0).abs() < 1e-15);
    /// assert!((Math::atan(f64::INFINITY) - Math::PI / 2.0).abs() < 1e-15);
    /// ```
    #[inline]
    pub fn atan(x: f64) -> f64 {
        x.atan()
    }

    /// Computes the inverse hyperbolic tangent ($\operatorname{artanh}$) of `x`.
    ///
    /// Mathematically defined as $\operatorname{atanh}(x) = \frac{1}{2}\ln\left(\frac{1+x}{1-x}\right)$.
    ///
    /// Mirrors JavaScript's `Math.atanh(x)`.
    ///
    /// # Domain & Special Values
    /// - Defined for $x \in (-1.0, 1.0)$.
    /// - For $|x| > 1.0$, returns `NaN`.
    /// - If `x` is `1.0`, returns `+Infinity`.
    /// - If `x` is `-1.0`, returns `-Infinity`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::atanh(0.0), 0.0);
    /// assert!((Math::atanh(0.5) - 0.5493061443340549).abs() < 1e-15);
    /// assert_eq!(Math::atanh(1.0), f64::INFINITY);
    /// assert_eq!(Math::atanh(-1.0), f64::NEG_INFINITY);
    /// assert!(Math::atanh(2.0).is_nan());
    /// ```
    #[inline]
    pub fn atanh(x: f64) -> f64 {
        x.atanh()
    }

    /// Computes the angle in the Euclidean plane (in radians) between the positive $x$-axis
    /// and the ray pointing to the coordinate $(x, y)$.
    ///
    /// Unlike `atan(y / x)`, `atan2(y, x)` uses the signs of both arguments to correctly determine
    /// the quadrant of the angle in the full range $[-\pi, +\pi]$.
    ///
    /// Mirrors JavaScript's `Math.atan2(y, x)`.
    ///
    /// # Quadrant Mapping
    /// - Quadrant I ($x > 0, y > 0$): $(0, \pi/2)$
    /// - Quadrant II ($x < 0, y > 0$): $(\pi/2, \pi]$
    /// - Quadrant III ($x < 0, y < 0$): $[-\pi, -\pi/2)$
    /// - Quadrant IV ($x > 0, y < 0$): $(-\pi/2, 0)$
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::atan2(0.0, 1.0), 0.0);
    /// assert!((Math::atan2(1.0, 1.0) - Math::PI / 4.0).abs() < 1e-15);
    /// assert_eq!(Math::atan2(0.0, -0.0), Math::PI);
    /// assert_eq!(Math::atan2(-0.0, -0.0), -Math::PI);
    /// ```
    #[inline]
    pub fn atan2(y: f64, x: f64) -> f64 {
        y.atan2(x)
    }

    /// Computes the real cube root $\sqrt\[3\]{x}$ of a number.
    ///
    /// Unlike the square root function, `cbrt` is defined for all negative real numbers
    /// (e.g. $\sqrt\[3\]{-8} = -2$).
    ///
    /// Mirrors JavaScript's `Math.cbrt(x)`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::cbrt(27.0), 3.0);
    /// assert_eq!(Math::cbrt(-8.0), -2.0);
    /// assert_eq!(Math::cbrt(1.0), 1.0);
    /// assert_eq!(Math::cbrt(0.0), 0.0);
    /// ```
    #[inline]
    pub fn cbrt(x: f64) -> f64 {
        x.cbrt()
    }

    /// Computes the ceiling of a number $\lceil x \rceil$ (the smallest integer greater than or equal to `x`).
    ///
    /// Mirrors JavaScript's `Math.ceil(x)`.
    ///
    /// # Special Values
    /// - If `x` is in $(-1.0, -0.0]$, returns `-0.0`.
    /// - If `x` is `NaN`, `+Infinity`, or `-Infinity`, returns `x`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::ceil(3.1), 4.0);
    /// assert_eq!(Math::ceil(3.9), 4.0);
    /// assert_eq!(Math::ceil(-3.1), -3.0);
    /// assert_eq!(Math::ceil(-3.9), -3.0);
    /// assert_eq!(Math::ceil(-0.5), -0.0);
    /// ```
    #[inline]
    pub fn ceil(x: f64) -> f64 {
        x.ceil()
    }

    /// Counts the number of leading zero bits in the 32-bit binary representation of `x`.
    ///
    /// If `x` is a floating-point number, it is first converted to a 32-bit unsigned integer
    /// via ECMAScript `ToUint32` (wrapping modulo $2^{32}$, with `NaN` and $\pm\infty$ yielding 0).
    ///
    /// Mirrors JavaScript's `Math.clz32(x)`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::clz32(1), 31);         // 00000000_00000000_00000000_00000001
    /// assert_eq!(Math::clz32(1000), 22);      // binary: 1111101000 (10 bits, 22 leading zeros)
    /// assert_eq!(Math::clz32(0), 32);         // 32 zeros
    /// assert_eq!(Math::clz32(-1), 0);         // 0xFFFFFFFF has 0 leading zeros
    /// assert_eq!(Math::clz32(f64::NAN), 32);  // Non-finite values coerce to 0
    /// ```
    #[inline]
    pub fn clz32<T: ToJsUint32>(x: T) -> u32 {
        x.to_js_uint32().leading_zeros()
    }

    /// Computes the cosine of angle `x` (measured in radians).
    ///
    /// Periodic with period $2\pi$, returning values in $[-1.0, 1.0]$.
    ///
    /// Mirrors JavaScript's `Math.cos(x)`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::cos(0.0), 1.0);
    /// assert!((Math::cos(Math::PI) - (-1.0)).abs() < 1e-15);
    /// assert!((Math::cos(Math::PI / 2.0)).abs() < 1e-15);
    /// ```
    #[inline]
    pub fn cos(x: f64) -> f64 {
        x.cos()
    }

    /// Computes the hyperbolic cosine of `x`.
    ///
    /// Mathematically defined as $\cosh(x) = \frac{e^x + e^{-x}}{2}$.
    ///
    /// Mirrors JavaScript's `Math.cosh(x)`.
    ///
    /// # Codomain & Special Values
    /// - Always $\ge 1.0$ for real numbers.
    /// - `Math::cosh(0.0) == 1.0`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::cosh(0.0), 1.0);
    /// assert_eq!(Math::cosh(1.0), 1.5430806348152437);
    /// assert_eq!(Math::cosh(-1.0), 1.5430806348152437);
    /// ```
    #[inline]
    pub fn cosh(x: f64) -> f64 {
        x.cosh()
    }

    /// Computes Euler's constant $e$ raised to the power of `x` ($e^x$).
    ///
    /// Inverse function of natural logarithm [`Math::log`].
    ///
    /// Mirrors JavaScript's `Math.exp(x)`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::exp(0.0), 1.0);
    /// assert_eq!(Math::exp(1.0), Math::E);
    /// assert_eq!(Math::exp(-f64::INFINITY), 0.0);
    /// ```
    #[inline]
    pub fn exp(x: f64) -> f64 {
        x.exp()
    }

    /// Computes $e^x - 1$ accurately, especially for values of `x` close to zero.
    ///
    /// For very small `x`, calculating `Math::exp(x) - 1.0` suffers from severe loss of
    /// floating-point precision due to catastrophic cancellation. `expm1` maintains full precision.
    ///
    /// Mirrors JavaScript's `Math.expm1(x)`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::expm1(0.0), 0.0);
    /// assert!((Math::expm1(1.0) - (Math::E - 1.0)).abs() < 1e-15);
    /// assert!((Math::expm1(1e-15) - 1e-15).abs() < 1e-18);
    /// ```
    #[inline]
    pub fn expm1(x: f64) -> f64 {
        x.exp_m1()
    }

    /// Computes the floor of a number $\lfloor x \rfloor$ (the largest integer less than or equal to `x`).
    ///
    /// Mirrors JavaScript's `Math.floor(x)`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::floor(3.9), 3.0);
    /// assert_eq!(Math::floor(3.1), 3.0);
    /// assert_eq!(Math::floor(-3.1), -4.0);
    /// assert_eq!(Math::floor(-3.9), -4.0);
    /// ```
    #[inline]
    pub fn floor(x: f64) -> f64 {
        x.floor()
    }

    /// Rounds a 64-bit float to the nearest 32-bit single-precision float representation,
    /// returning the result as an `f64`.
    ///
    /// Useful for simulating 32-bit floating-point math as used in WebGL, shaders, and JavaScript.
    ///
    /// Mirrors JavaScript's `Math.fround(x)`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::fround(1.337), 1.3370000123977661);
    /// assert_eq!(Math::fround(1.5), 1.5);
    /// assert_eq!(Math::fround(0.0), 0.0);
    /// ```
    #[inline]
    pub fn fround(x: f64) -> f64 {
        (x as f32) as f64
    }

    /// Rounds a 64-bit float to the nearest 16-bit half-precision float (IEEE 754 binary16),
    /// returning the result as an `f64`.
    ///
    /// Corresponds to ECMAScript 2024 `Math.f16round(x)`. Useful for machine learning, graphics,
    /// and reduced-precision float interoperability.
    ///
    /// # Precision & Limits
    /// - Maximum finite value: `65504.0`.
    /// - Values $\ge 65520.0$ overflow to $\pm\infty$.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::f16round(1.337), 1.3369140625);
    /// assert_eq!(Math::f16round(Math::PI), 3.140625);
    /// assert_eq!(Math::f16round(65504.0), 65504.0);
    /// assert_eq!(Math::f16round(65520.0), f64::INFINITY);
    /// ```
    #[inline]
    pub fn f16round(x: f64) -> f64 {
        f16::f16round(x)
    }

    /// Computes the square root of the sum of squares of a slice of numbers ($\sqrt{\sum x_i^2}$).
    ///
    /// Employs internal scaling to prevent intermediate overflow (e.g. $(10^{300})^2$)
    /// and underflow (e.g. $(10^{-300})^2$).
    ///
    /// Mirrors JavaScript's `Math.hypot(...values)`.
    ///
    /// # Special Values
    /// - An empty slice `&[]` returns `0.0`.
    /// - If any argument is $\pm\infty$, returns $+\infty$ (even if another argument is `NaN`).
    /// - If any argument is `NaN` and no argument is infinite, returns `NaN`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::hypot(&[3.0, 4.0]), 5.0);
    /// assert_eq!(Math::hypot(&[1.0, 2.0, 2.0]), 3.0);
    /// assert_eq!(Math::hypot(&[]), 0.0);
    ///
    /// // Special rule: Infinity overrides NaN:
    /// assert_eq!(Math::hypot(&[f64::INFINITY, f64::NAN]), f64::INFINITY);
    /// ```
    #[inline]
    pub fn hypot(values: &[f64]) -> f64 {
        if values.is_empty() {
            return 0.0;
        }
        for &v in values {
            if v.is_infinite() {
                return f64::INFINITY;
            }
        }
        for &v in values {
            if v.is_nan() {
                return f64::NAN;
            }
        }
        let mut max = 0.0f64;
        for &v in values {
            let abs_v = v.abs();
            if abs_v > max {
                max = abs_v;
            }
        }
        if max == 0.0 {
            return 0.0;
        }
        let mut sum = 0.0f64;
        for &v in values {
            let scaled = v / max;
            sum += scaled * scaled;
        }
        max * sum.sqrt()
    }

    /// Computes the hypotenuse of two numbers $\sqrt{x^2 + y^2}$.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::hypot2(3.0, 4.0), 5.0);
    /// assert_eq!(Math::hypot2(f64::INFINITY, f64::NAN), f64::INFINITY);
    /// ```
    #[inline]
    pub fn hypot2(x: f64, y: f64) -> f64 {
        if x.is_infinite() || y.is_infinite() {
            return f64::INFINITY;
        }
        if x.is_nan() || y.is_nan() {
            return f64::NAN;
        }
        x.hypot(y)
    }

    /// Computes the 32-bit integer multiplication of `a` and `b` ($a \times b \pmod{2^{32}}$).
    ///
    /// Provides C-like 32-bit signed wrapping multiplication, widely used in hashing algorithms,
    /// cryptographic routines, and games.
    ///
    /// Mirrors JavaScript's `Math.imul(a, b)`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::imul(2, 4), 8);
    /// assert_eq!(Math::imul(-1, 8), -8);
    /// assert_eq!(Math::imul(0xffff_ffffu32, 5), -5);
    /// assert_eq!(Math::imul(0.5, 2.5), 0);
    /// ```
    #[inline]
    pub fn imul<A: ToJsInt32, B: ToJsInt32>(a: A, b: B) -> i32 {
        a.to_js_int32().wrapping_mul(b.to_js_int32())
    }

    /// Computes the natural logarithm (base $e$) of `x` ($\ln(x)$).
    ///
    /// Mirrors JavaScript's `Math.log(x)`.
    ///
    /// # Domain & Special Values
    /// - Defined for $x > 0$.
    /// - For $x < 0$, returns `NaN`.
    /// - If `x` is `0.0`, returns `-Infinity`.
    /// - `Math::log(Math::E) == 1.0`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::log(1.0), 0.0);
    /// assert_eq!(Math::log(Math::E), 1.0);
    /// assert_eq!(Math::log(0.0), f64::NEG_INFINITY);
    /// assert!(Math::log(-1.0).is_nan());
    /// ```
    #[inline]
    pub fn log(x: f64) -> f64 {
        x.ln()
    }

    /// Computes the natural logarithm of $1 + x$ ($\ln(1 + x)$) accurately.
    ///
    /// When `x` is near zero, calculating `Math::log(1.0 + x)` loses significant precision.
    /// `log1p` computes the result directly without precision loss.
    ///
    /// Mirrors JavaScript's `Math.log1p(x)`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::log1p(0.0), 0.0);
    /// assert_eq!(Math::log1p(1e-15), 9.999999999999995e-16);
    /// assert_eq!(Math::log1p(-1.0), f64::NEG_INFINITY);
    /// ```
    #[inline]
    pub fn log1p(x: f64) -> f64 {
        x.ln_1p()
    }

    /// Snake-case alias for [`Math::log1p`].
    #[inline]
    pub fn log_1p(x: f64) -> f64 {
        x.ln_1p()
    }

    /// Computes the base-10 logarithm of `x` ($\log_{10}(x)$).
    ///
    /// Returns the exponent to which 10 must be raised to produce `x`.
    ///
    /// Mirrors JavaScript's `Math.log10(x)`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::log10(1.0), 0.0);
    /// assert_eq!(Math::log10(10.0), 1.0);
    /// assert_eq!(Math::log10(100.0), 2.0);
    /// assert_eq!(Math::log10(1000.0), 3.0);
    /// ```
    #[inline]
    pub fn log10(x: f64) -> f64 {
        x.log10()
    }

    /// Snake-case alias for [`Math::log10`].
    #[inline]
    pub fn log_10(x: f64) -> f64 {
        x.log10()
    }

    /// Computes the base-2 logarithm of `x` ($\log_2(x)$).
    ///
    /// Returns the exponent to which 2 must be raised to produce `x`.
    ///
    /// Mirrors JavaScript's `Math.log2(x)`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::log2(1.0), 0.0);
    /// assert_eq!(Math::log2(2.0), 1.0);
    /// assert_eq!(Math::log2(8.0), 3.0);
    /// assert_eq!(Math::log2(1024.0), 10.0);
    /// ```
    #[inline]
    pub fn log2(x: f64) -> f64 {
        x.log2()
    }

    /// Snake-case alias for [`Math::log2`].
    #[inline]
    pub fn log_2(x: f64) -> f64 {
        x.log2()
    }

    /// Returns the largest number from a slice of floating-point numbers.
    ///
    /// Mirrors JavaScript's `Math.max(...values)`.
    ///
    /// # ECMAScript Rules
    /// - An empty slice `&[]` returns $-\infty$ (`f64::NEG_INFINITY`).
    /// - If any item is `NaN`, returns `NaN`.
    /// - `+0.0` is strictly greater than `-0.0` (`Math::max(&[-0.0, 0.0]) == +0.0`).
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::max(&[10.0, 20.0, -5.0]), 20.0);
    /// assert_eq!(Math::max(&[]), f64::NEG_INFINITY);
    /// assert!(Math::max(&[1.0, f64::NAN]).is_nan());
    ///
    /// let res = Math::max(&[-0.0, 0.0]);
    /// assert_eq!(res, 0.0);
    /// assert!(res.is_sign_positive());
    /// ```
    #[inline]
    pub fn max(values: &[f64]) -> f64 {
        if values.is_empty() {
            return f64::NEG_INFINITY;
        }
        let mut res = f64::NEG_INFINITY;
        for &v in values {
            if v.is_nan() {
                return f64::NAN;
            }
            if v > res {
                res = v;
            }
            if v == 0.0 && res == 0.0 && v.is_sign_positive() {
                res = 0.0;
            }
        }
        res
    }

    /// Returns the greater of two numbers `a` and `b`.
    ///
    /// Distinguishes between `+0.0` and `-0.0` by treating `+0.0 > -0.0`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::max2(3.0, 5.0), 5.0);
    /// assert_eq!(Math::max2(-3.0, -5.0), -3.0);
    ///
    /// let res = Math::max2(-0.0, 0.0);
    /// assert_eq!(res, 0.0);
    /// assert!(res.is_sign_positive());
    /// ```
    #[inline]
    pub fn max2(a: f64, b: f64) -> f64 {
        if a.is_nan() || b.is_nan() {
            f64::NAN
        } else if a == 0.0 && b == 0.0 {
            if a.is_sign_positive() || b.is_sign_positive() {
                0.0
            } else {
                -0.0
            }
        } else if a > b {
            a
        } else {
            b
        }
    }

    /// Returns the smallest number from a slice of floating-point numbers.
    ///
    /// Mirrors JavaScript's `Math.min(...values)`.
    ///
    /// # ECMAScript Rules
    /// - An empty slice `&[]` returns $+\infty$ (`f64::INFINITY`).
    /// - If any item is `NaN`, returns `NaN`.
    /// - `-0.0` is strictly smaller than `+0.0` (`Math::min(&[-0.0, 0.0]) == -0.0`).
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::min(&[10.0, 20.0, -5.0]), -5.0);
    /// assert_eq!(Math::min(&[]), f64::INFINITY);
    /// assert!(Math::min(&[1.0, f64::NAN]).is_nan());
    ///
    /// let res = Math::min(&[0.0, -0.0]);
    /// assert_eq!(res, 0.0);
    /// assert!(res.is_sign_negative());
    /// ```
    #[inline]
    pub fn min(values: &[f64]) -> f64 {
        if values.is_empty() {
            return f64::INFINITY;
        }
        let mut res = f64::INFINITY;
        for &v in values {
            if v.is_nan() {
                return f64::NAN;
            }
            if v < res {
                res = v;
            }
            if v == 0.0 && res == 0.0 && v.is_sign_negative() {
                res = -0.0;
            }
        }
        res
    }

    /// Returns the smaller of two numbers `a` and `b`.
    ///
    /// Distinguishes between `+0.0` and `-0.0` by treating `-0.0 < +0.0`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::min2(3.0, 5.0), 3.0);
    /// assert_eq!(Math::min2(-3.0, -5.0), -5.0);
    ///
    /// let res = Math::min2(0.0, -0.0);
    /// assert_eq!(res, 0.0);
    /// assert!(res.is_sign_negative());
    /// ```
    #[inline]
    pub fn min2(a: f64, b: f64) -> f64 {
        if a.is_nan() || b.is_nan() {
            f64::NAN
        } else if a == 0.0 && b == 0.0 {
            if a.is_sign_negative() || b.is_sign_negative() {
                -0.0
            } else {
                0.0
            }
        } else if a < b {
            a
        } else {
            b
        }
    }

    /// Computes the base `base` raised to the power of `exponent` ($base^{exponent}$).
    ///
    /// Implements exact ECMAScript power rules:
    /// - Any base (including `NaN`) to power `0.0` or `-0.0` yields `1.0`.
    /// - Base `1.0` or `-1.0` to infinite power yields `NaN`.
    /// - Negative base with non-integer exponent yields `NaN`.
    /// - Negative zero base sign propagation with odd vs. even exponents.
    ///
    /// Mirrors JavaScript's `Math.pow(base, exponent)`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::pow(2.0, 3.0), 8.0);
    /// assert_eq!(Math::pow(4.0, 0.5), 2.0);
    /// assert_eq!(Math::pow(2.0, -1.0), 0.5);
    ///
    /// // Special ECMAScript rules:
    /// assert_eq!(Math::pow(f64::NAN, 0.0), 1.0);
    /// assert!(Math::pow(1.0, f64::INFINITY).is_nan());
    /// assert_eq!(Math::pow(-0.0, -1.0), f64::NEG_INFINITY);
    /// ```
    #[inline]
    pub fn pow(base: f64, exponent: f64) -> f64 {
        if exponent == 0.0 {
            return 1.0;
        }
        if exponent.is_nan() {
            return f64::NAN;
        }
        if base.is_nan() {
            return f64::NAN;
        }
        if base.abs() == 1.0 && exponent.is_infinite() {
            return f64::NAN;
        }
        if base == 0.0 && base.is_sign_negative() {
            let is_odd = is_odd_integer(exponent);
            if exponent > 0.0 {
                return if is_odd { -0.0 } else { 0.0 };
            } else {
                return if is_odd {
                    f64::NEG_INFINITY
                } else {
                    f64::INFINITY
                };
            }
        }
        if base == f64::NEG_INFINITY {
            let is_odd = is_odd_integer(exponent);
            if exponent > 0.0 {
                return if is_odd {
                    f64::NEG_INFINITY
                } else {
                    f64::INFINITY
                };
            } else {
                return if is_odd { -0.0 } else { 0.0 };
            }
        }
        if base < 0.0 && base.is_finite() && exponent.is_finite() && exponent.floor() != exponent {
            return f64::NAN;
        }
        base.powf(exponent)
    }

    /// Returns a pseudo-random floating-point number in the half-open interval $[0.0, 1.0)$.
    ///
    /// Uses a zero-dependency, thread-safe, high-speed Xoshiro256++ generator with period $2^{256} - 1$.
    ///
    /// Mirrors JavaScript's `Math.random()`.
    ///
    /// # Note
    /// Like JavaScript's `Math.random()`, this generator is designed for simulations, games,
    /// and algorithms, and is **not** cryptographically secure.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// let r = Math::random();
    /// assert!(r >= 0.0);
    /// assert!(r < 1.0);
    /// ```
    #[inline]
    pub fn random() -> f64 {
        random::random()
    }

    /// Sets the thread-local seed for [`Math::random`].
    ///
    /// Enables deterministic, reproducible random sequences for testing and benchmarks.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// Math::seed_random(12345);
    /// let val1 = Math::random();
    ///
    /// Math::seed_random(12345);
    /// let val2 = Math::random();
    ///
    /// assert_eq!(val1, val2);
    /// ```
    #[inline]
    pub fn seed_random(seed: u64) {
        random::seed_random(seed);
    }

    /// Rounds a number to the nearest integer using ECMAScript's "half-up" tie-breaking rule.
    ///
    /// # Tie-breaking & Differences from Standard Rust
    /// - Standard Rust (`f64::round`) breaks ties by rounding half away from zero (`-0.5 -> -1.0`, `-1.5 -> -2.0`).
    /// - ECMAScript `Math.round` breaks ties by rounding toward $+\infty$:
    ///   - `Math::round(-0.5) == -0.0`
    ///   - `Math::round(-1.5) == -1.0`
    ///   - `Math::round(1.5) == 2.0`
    ///
    /// Mirrors JavaScript's `Math.round(x)`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::round(1.5), 2.0);
    /// assert_eq!(Math::round(1.4), 1.0);
    /// assert_eq!(Math::round(-1.5), -1.0);
    ///
    /// let res = Math::round(-0.5);
    /// assert_eq!(res, 0.0);
    /// assert!(res.is_sign_negative(), "-0.5 rounds to -0.0");
    /// ```
    #[inline]
    pub fn round(x: f64) -> f64 {
        if x.is_nan() || !x.is_finite() || x == 0.0 {
            return x;
        }
        if (-0.5..0.0).contains(&x) {
            return -0.0;
        }
        if (0.0..0.5).contains(&x) {
            return 0.0;
        }
        // Floats with magnitude >= 2^52 are strictly integers with no fractional part
        if x.abs() >= 4503599627370496.0 {
            return x;
        }
        let fl = x.floor();
        let frac = x - fl;
        if frac >= 0.5 {
            let cl = x.ceil();
            if cl == 0.0 && x < 0.0 {
                -0.0
            } else {
                cl
            }
        } else {
            if fl == 0.0 && x < 0.0 {
                -0.0
            } else {
                fl
            }
        }
    }

    /// Returns `+1.0`, `-1.0`, `+0.0`, `-0.0`, or `NaN` indicating the sign of `x`.
    ///
    /// Unlike Rust's standard `f64::signum()` (which maps `0.0` to `1.0`), this function preserves
    /// positive and negative zeros.
    ///
    /// Mirrors JavaScript's `Math.sign(x)`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::sign(3.0), 1.0);
    /// assert_eq!(Math::sign(-3.0), -1.0);
    ///
    /// let pos_zero = Math::sign(0.0);
    /// assert_eq!(pos_zero, 0.0);
    /// assert!(pos_zero.is_sign_positive());
    ///
    /// let neg_zero = Math::sign(-0.0);
    /// assert_eq!(neg_zero, 0.0);
    /// assert!(neg_zero.is_sign_negative());
    ///
    /// assert!(Math::sign(f64::NAN).is_nan());
    /// ```
    #[inline]
    pub fn sign(x: f64) -> f64 {
        if x.is_nan() {
            f64::NAN
        } else if x == 0.0 {
            x
        } else if x > 0.0 {
            1.0
        } else {
            -1.0
        }
    }

    /// Computes the sine of angle `x` (measured in radians).
    ///
    /// Periodic with period $2\pi$, returning values in $[-1.0, 1.0]$.
    ///
    /// Mirrors JavaScript's `Math.sin(x)`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::sin(0.0), 0.0);
    /// assert!((Math::sin(Math::PI / 2.0) - 1.0).abs() < 1e-15);
    /// assert!((Math::sin(-Math::PI / 2.0) - (-1.0)).abs() < 1e-15);
    /// ```
    #[inline]
    pub fn sin(x: f64) -> f64 {
        x.sin()
    }

    /// Computes the hyperbolic sine of `x`.
    ///
    /// Mathematically defined as $\sinh(x) = \frac{e^x - e^{-x}}{2}$.
    ///
    /// Mirrors JavaScript's `Math.sinh(x)`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::sinh(0.0), 0.0);
    /// assert_eq!(Math::sinh(1.0), 1.1752011936438014);
    /// assert_eq!(Math::sinh(-1.0), -1.1752011936438014);
    /// ```
    #[inline]
    pub fn sinh(x: f64) -> f64 {
        x.sinh()
    }

    /// Computes the square root $\sqrt{x}$ of a non-negative number.
    ///
    /// Returns the positive number $y$ such that $y^2 = x$.
    ///
    /// Mirrors JavaScript's `Math.sqrt(x)`.
    ///
    /// # Domain & Special Values
    /// - Defined for $x \ge 0$.
    /// - For $x < 0$, returns `NaN`.
    /// - `Math::sqrt(0.0) == 0.0`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::sqrt(9.0), 3.0);
    /// assert_eq!(Math::sqrt(2.0), Math::SQRT2);
    /// assert_eq!(Math::sqrt(0.0), 0.0);
    /// assert!(Math::sqrt(-1.0).is_nan());
    /// ```
    #[inline]
    pub fn sqrt(x: f64) -> f64 {
        x.sqrt()
    }

    /// Computes the exact, compensated sum of a collection of floating-point numbers
    /// without intermediate rounding errors (Shewchuk algorithm).
    ///
    /// Standard floating-point addition suffers from catastrophic cancellation when summing numbers
    /// of widely different magnitudes (e.g. `(1e16 + 1.0) - 1e16` evaluates to `0.0`).
    /// `sumPrecise` preserves all bits of precision and produces the exact mathematical result `1.0`.
    ///
    /// Corresponds to ECMAScript 2024 `Math.sumPrecise(items)`.
    ///
    /// # Special Values
    /// - An empty collection returns `0.0`.
    /// - If any element is `NaN` or both `+Infinity` and `-Infinity` are present, returns `NaN`.
    /// - If all elements are `-0.0`, returns `-0.0`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// // Catastrophic cancellation eliminated:
    /// let numbers = [1e16, 1.0, -1e16];
    /// assert_eq!(Math::sumPrecise(&numbers), 1.0);
    ///
    /// let small_numbers = [1e-16, 1.0, -1.0];
    /// assert_eq!(Math::sumPrecise(&small_numbers), 1e-16);
    /// ```
    #[inline]
    pub fn sumPrecise<'a, I>(items: I) -> f64
    where
        I: IntoIterator<Item = &'a f64>,
    {
        sum_precise::sum_precise(items)
    }

    /// Snake-case alias for [`Math::sumPrecise`].
    #[inline]
    pub fn sum_precise<'a, I>(items: I) -> f64
    where
        I: IntoIterator<Item = &'a f64>,
    {
        sum_precise::sum_precise(items)
    }

    /// Computes the tangent of angle `x` (measured in radians).
    ///
    /// Mathematically defined as $\tan(x) = \frac{\sin x}{\cos x}$.
    ///
    /// Mirrors JavaScript's `Math.tan(x)`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::tan(0.0), 0.0);
    /// assert!((Math::tan(Math::PI / 4.0) - 1.0).abs() < 1e-15);
    /// ```
    #[inline]
    pub fn tan(x: f64) -> f64 {
        x.tan()
    }

    /// Computes the hyperbolic tangent of `x`.
    ///
    /// Mathematically defined as $\tanh(x) = \frac{\sinh x}{\cosh x} = \frac{e^{2x} - 1}{e^{2x} + 1}$.
    ///
    /// Codomain is $(-1.0, 1.0)$ for all finite numbers.
    ///
    /// Mirrors JavaScript's `Math.tanh(x)`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::tanh(0.0), 0.0);
    /// assert_eq!(Math::tanh(f64::INFINITY), 1.0);
    /// assert_eq!(Math::tanh(f64::NEG_INFINITY), -1.0);
    /// ```
    #[inline]
    pub fn tanh(x: f64) -> f64 {
        x.tanh()
    }

    /// Returns the integer part of `x` by discarding any fractional digits (rounding toward zero).
    ///
    /// Mirrors JavaScript's `Math.trunc(x)`.
    ///
    /// # Examples
    ///
    /// ```
    /// use MathUtils::Math;
    ///
    /// assert_eq!(Math::trunc(3.9), 3.0);
    /// assert_eq!(Math::trunc(3.1), 3.0);
    /// assert_eq!(Math::trunc(-3.9), -3.0);
    /// assert_eq!(Math::trunc(-3.1), -3.0);
    /// ```
    #[inline]
    pub fn trunc(x: f64) -> f64 {
        x.trunc()
    }
}

#[inline]
fn is_odd_integer(x: f64) -> bool {
    x.is_finite() && x.floor() == x && (x % 2.0).abs() == 1.0
}