mathexpr

A fast, safe mathematical expression parser and evaluator for Rust.

Features

• Fast - Compiles expressions to bytecode for efficient repeated evaluation (~15-80ns per eval)
• Safe - No unsafe code, proper error handling
• no_std compatible - Works in embedded environments with alloc
• Rich function library - 27 built-in functions including trig, logarithms, rounding, and more

Quick Start

use mathexpr::Expression;

// Parse, compile, and evaluate
let expr = Expression::parse("sqrt(x^2 + y^2)")?
    .compile(&["x", "y"])?;

assert_eq!(expr.eval(&[3.0, 4.0])?, 5.0);
assert_eq!(expr.eval(&[5.0, 12.0])?, 13.0);

One-liner Evaluation

For simple cases where you don't need to reuse the compiled expression:

use mathexpr::eval;

let result = eval("2 * pi * r", &["r"], &[5.0])?;
// result ≈ 31.4159

Current Value (_)

Use _ to reference an input value, useful for transformations:

use mathexpr::Expression;

let normalize = Expression::parse("(_ - min) / (max - min)")?
    .compile(&["min", "max"])?;

// Normalize 50 to range [0, 100]
let result = normalize.eval_with_current(50.0, &[0.0, 100.0])?;
assert_eq!(result, 0.5);

Operators

Functions

Core Math

Trigonometric

Rounding

Constants

Error Handling

mathexpr provides three error types:

use mathexpr::{Expression, ParseError, CompileError, EvalError};

// Parse errors - invalid syntax
match Expression::parse("@#$") {
    Err(ParseError::InvalidSyntax(msg)) => { /* handle */ }
    Err(ParseError::UnexpectedTrailingInput(s)) => { /* handle */ }
    _ => {}
}

// Compile errors - undefined variables or unknown functions
match Expression::parse("x + y")?.compile(&["x"]) {
    Err(CompileError::UndefinedVariable(name)) => { /* handle */ }
    Err(CompileError::UnknownFunction(name)) => { /* handle */ }
    Err(CompileError::WrongArity { name, expected, got }) => { /* handle */ }
    _ => {}
}

// Eval errors - runtime errors
match expr.eval(&[0.0]) {
    Err(EvalError::DivisionByZero) => { /* handle */ }
    _ => {}
}

Note: Domain errors (like sqrt(-1)) return NaN rather than errors.

Performance

Typical evaluation times on modern hardware:

Examples

Run the included examples:

# Basic API usage
cargo run --example basic

# Error handling patterns
cargo run --example errors

# Interactive calculator with history
cargo run --example repl

Feature Flags

For no_std environments:

[dependencies]
mathexpr = { version = "0.1", default-features = false }

Requires the alloc crate.

License

MIT License. See LICENSE for details.