expr-solver

A mathematical expression evaluator library written in Rust with support for custom functions, constants, and bytecode compilation.

Features

• Mathematical expressions - Arithmetic, comparisons, and built-in functions
• Flexible numeric types - Choose between fast f64 (default) or high-precision 128-bit Decimal
• Custom symbols - Register your own constants and functions
• Rich error messages - Syntax errors with source location highlighting
• Bytecode compilation - Compile expressions to portable binary format
• Stack-based VM - Efficient execution on a virtual machine

What's it For?

Need to evaluate math but don't want to embed an entire scripting language? You're in the right place. 🎯

Perfect for:

• Game engines - Calculate damage formulas, level requirements, or item stats without hardcoding values
• Configuration files - Let users write price * 0.9 instead of forcing them to update every value manually
• Analytics dashboards - Enable power users to define custom metrics: (revenue - cost) / users
• Form calculators - Mortgage calculators, unit converters, or any user-facing math
• Educational tools - Math tutoring apps, graphing calculators, or homework helpers
• Learning compilers - Clean example of lexer, parser, and stack-based VM in ~2K lines of Rust

How It Works

Classic compiler pipeline with type-safe state transitions:

Input → Lexer → Parser → Compiler → Program<Compiled>
                                           ↓ link
                                    Program<Linked> → Execute

The Program type uses Rust's type system to enforce correct usage at compile time. You cannot execute an unlinked program, and you cannot link a program twice.

Usage

As a Library

Add this to your Cargo.toml:

[dependencies]
expr-solver-lib = "1.2.0"

Numeric Type Selection:

The library supports two numeric backends via feature flags (mutually exclusive):

• f64-floats (default) - Standard f64 floating-point arithmetic. Faster and simpler, allows Inf and NaN results.
• decimal-precision - 128-bit Decimal for high precision. No floating-point errors, checked arithmetic with overflow detection.

To use high-precision Decimal:

[dependencies]
expr-solver-lib = { version = "1.2.0", default-features = false, features = ["decimal-precision"] }

To enable bytecode serialization with f64:

[dependencies]
expr-solver-lib = { version = "1.2.0", features = ["serialization"] }

To enable bytecode serialization with Decimal:

[dependencies]
expr-solver-lib = { version = "1.2.0", default-features = false, features = ["decimal-precision", "serialization"] }

As a binary

Add this to your Cargo.toml:

[dependencies]
expr-solver-bin = "1.2.0"

Quick Evaluation

use expr_solver::eval;

// Simple one-liner
let result = eval("2 + 3 * 4").unwrap();
assert_eq!(result.to_string(), "14");

// With built-in functions
let result = eval("sqrt(16) + sin(pi/2)").unwrap();

Custom Symbols

use expr_solver::{eval_with_table, SymTable, Number, ParseNumber};

let mut table = SymTable::stdlib();
table.add_const("x", Number::parse_number("10").unwrap()).unwrap();
table.add_func("double", 1, false, |args| {
    Ok(args[0] * Number::parse_number("2").unwrap())
}).unwrap();

let result = eval_with_table("double(x)", table).unwrap();
assert_eq!(result.to_string(), "20");

Or with f64 (default):

use expr_solver::{eval_with_table, SymTable};

let mut table = SymTable::stdlib();
table.add_const("x", 10.0).unwrap();
table.add_func("double", 1, false, |args| Ok(args[0] * 2.0)).unwrap();

let result = eval_with_table("double(x)", table).unwrap();
assert_eq!(result, 20.0);

Compile Once, Execute Many Times

use expr_solver::{Program, SymTable};

// Compile expression
let program = Program::new_from_source("x * 2 + y").unwrap();

// Execute with different values
let mut table = SymTable::new();
table.add_const("x", 10.0).unwrap();
table.add_const("y", 5.0).unwrap();

let linked = program.link(table).unwrap();
let result = linked.execute().unwrap(); // 25.0
assert_eq!(result, 25.0);

Numeric Precision

The library supports two numeric backends:

f64 (Default)

• Standard IEEE 754 double-precision floating-point
• Fast and efficient for most use cases
• Allows Inf and NaN results (e.g., 1/0 → Inf, sqrt(-1) → NaN)
• Minimal error checking - only prevents panics

Decimal (Optional)

• 128-bit fixed-point arithmetic via rust_decimal
• Exact decimal representation (no 0.1 + 0.2 ≠ 0.3 issues)
• Checked arithmetic with overflow/underflow detection
• Domain validation (e.g., sqrt(-1) returns an error)
• Ideal for financial calculations or when exact decimal precision is required

Choosing the right mode:

• Use f64 (default) for general-purpose math, scientific computing, or when performance is critical
• Use Decimal for financial applications, accounting, or when exact decimal representation is required

Built-in Functions

Note: In decimal-precision mode, some operations (inverse trig, pow) use internal f64 conversion due to rust_decimal limitations, which may introduce small precision loss.

Built-in Constants

pi, e, tau, ln2, ln10, sqrt2

All names are case-insensitive.

Operators

Arithmetic: +, -, *, /, ^ (power), ! (factorial), unary - Comparison: ==, !=, <, <=, >, >= (returns 1 or 0) Grouping: ( )

Command Line Usage

# Evaluate an expression
expr-solver "2 + 3 * 4"

# Use the -e flag
expr-solver -e "sin(pi/2)"

# Define custom constants
expr-solver -D x=10 -D y=20 "x + y"

# Compile to binary
expr-solver -e "2+3*4" -o expr.bin

# Execute compiled binary
expr-solver -i expr.bin

# View assembly from expression or file
expr-solver -e "2+3" -a
expr-solver -i expr.bin -a

# Recompile bytecode (e.g., version migration)
expr-solver -i old.bin -o new.bin

# List available functions and constants
expr-solver -t

Testing

Run the test suite:

# Run all tests with default f64 mode
cargo test

# Test with decimal-precision mode
cargo test -p expr-solver-lib --no-default-features --features decimal-precision

# Test binary with f64 mode
cargo test -p expr-solver-bin

License

This project is licensed under the MIT License.