MathUtils

A high-performance, zero-dependency Rust crate that mirrors JavaScript's built-in Math object with exact ECMAScript 2024 semantics.

✨ Features

• Exact ECMAScript Semantics: Full fidelity with JavaScript Math, including subtle IEEE 754 edge cases:
  • Math::round(-0.5) == -0.0 (tie-breaking towards $+\infty$)
  • Math::sign(-0.0) == -0.0 and Math::sign(+0.0) == +0.0
  • Math::pow(NaN, 0.0) == 1.0 and Math::pow(1.0, Infinity) == NaN
  • Math::hypot with $\pm\infty$ overriding NaN
• Complete Constant Set: E, LN10, LN2, LOG10E, LOG2E, PI, SQRT1_2, SQRT2 (with snake_case aliases).
• All JavaScript Methods: abs, acos, acosh, asin, asinh, atan, atan2, atanh, cbrt, ceil, clz32, cos, cosh, exp, expm1, floor, fround, f16round (ES2024), hypot, imul, log, log1p, log10, log2, max, min, pow, random, round, sign, sin, sinh, sqrt, sumPrecise (ES2024), tan, tanh, trunc.
• Zero External Dependencies: Pure Rust standard library.
• Fast, Thread-Safe PRNG: High-performance Xoshiro256++ generator for Math::random() with thread-local state and seedable testing support.
• Variadic Macros: math_max!, math_min!, math_hypot! providing variadic JavaScript-style calling ergonomics.
• Clean Math Namespace: Access all constants and methods directly through the Math struct (Math::cos(...), Math::PI, Math::round(...)), mirroring JavaScript's syntax.

📦 Installation

Add to your Cargo.toml:

[dependencies]
MathUtils = "0.1.0"

Or run via cargo:

cargo add MathUtils

🚀 Quick Start

use MathUtils::{Math, math_max, math_min, math_hypot};

fn main() {
    // 1. Exact JavaScript Rounding
    assert_eq!(Math::round(-0.5), -0.0);
    assert_eq!(Math::round(1.5), 2.0);
    assert_eq!(Math::round(-1.5), -1.0);

    // 2. Constants & Trigonometry
    println!("Pi: {}", Math::PI);
    println!("Cos(0): {}", Math::cos(0.0));
    println!("Atan2(0, -0): {}", Math::atan2(0.0, -0.0)); // Pi

    // 3. Integer Operations & Type Coercion
    assert_eq!(Math::imul(0xffff_ffffu32, 5), -5);
    assert_eq!(Math::clz32(1000.0), 22);

    // 4. IEEE 754 Float Conversions
    assert_eq!(Math::fround(1.337), 1.3370000123977661);
    assert_eq!(Math::f16round(Math::PI), 3.140625);

    // 5. Compensated Exact Summation (ES2024 Math.sumPrecise)
    let numbers = [1e16, 1.0, -1e16];
    assert_eq!(Math::sumPrecise(&numbers), 1.0);

    // 6. Variadic Macros
    assert_eq!(math_max!(1.0, 99.5, -42.0), 99.5);
    assert_eq!(math_min!(1.0, 99.5, -42.0), -42.0);
    assert_eq!(math_hypot!(3.0, 4.0), 5.0);

    // 7. Pseudo-random Number Generation
    let r = Math::random();
    println!("Random in [0, 1): {}", r);
}

📚 Documentation

You can generate and view the complete HTML API documentation locally by running:

cargo doc --no-deps --open

📖 API Reference

Constants

Methods

🔍 JavaScript vs. Standard Rust Floating-Point Differences Handled

📜 License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.