Caldyn, dynamic evaluation of mathematical expressions

This crate provide run-time evaluation of mathematical expressions, embedded in strings, containing constants and user-provided variables. This can be used to evaluate user-provided expressions in a larger context.

Documentation

Usage

Add the crate to your Cargo.toml:

[dependencies]
caldyn = "0.3"

The easiest way to use this crate is with the eval function:

assert_eq!(caldyn::eval("3 + 5 * 2", None), Ok(13.0));

The second argument to eval is a Context, that can define variables:

use caldyn::Context;

let mut context = Context::new();
context.set("a", 3.5);
assert_eq!(caldyn::eval("2 * a", &context), Ok(7.0));

It is also possible to separate the parsing from the evaluation of an expression with the Expr type. This allow to reuse the same expression with different values for variables.

use caldyn::{Expr, Context};

let expr = Expr::parse("3 + 5 * 2").unwrap();
assert_eq!(expr.eval(None), Ok(13.0));

let expr = Expr::parse("3 / c + b").unwrap();
let mut context = Context::new();
context.set("c", 1.0);
context.set("b", 5.0);
assert_eq!(expr.eval(&context), Ok(8.0));

context.set("b", 10.0);
assert_eq!(expr.eval(&context), Ok(13.0));

It is also possible to set a callback function to be used when a variable is not found in the context:

use caldyn::{eval, Context};

let mut context = Context::new();
context.set_query(|name| {
    match name {
        "a" | "b" | "c" => Some(1.0),
        _ => None
    }
});

assert_eq!(eval("a + b", &context), Ok(2.0));
// the following line would error with "undefined variable 'd'" message
// eval("d / 2", &context);

Usage as a terminal calculator

You can use the calc example as your terminal calculator, installing it with cargo:

cargo install caldyn --example calc

Language definition

The language implemented by caldyn can contain the following elements:

float literal values: -12.456, +0.0045e78, ...;
left and right parenthesis;
mathematical operators: + for addition, - for subtraction, * for multiplication, / for division and ^ for exponentiation (std::f64::powf);
variables. Variables names are ASCII only, and can start by a letter or _, and can contain letters, digits, ., _, [ or ].
function call: sin(a), atan(22.0). The following function are accessible, with the same meaning as the corresponding std::f64 function: sqrt, cbrt, sin, cos, tan, asin, acos, atan, sinh, cosh, tanh, asinh, acosh, atanh, floor, ceil, abs, exp, ln, log2, log10.

Any other symbol is forbidden in the input.

The mathematical operators obey the usual relations of associativity and precedence, but still carry the floating point properties: addition is not commutative, NaN and infinities exist, ...

Please note that while [ and ] are allowed in variables names, nothing is done with them. Users of caldyn can parse and interpret these as indexing operators in their own [Context::set_query()] function.

License and contributions