Crate exmex[−][src]
Expand description
Exmex is a fast, simple, and extendable mathematical expression evaluator with the ability to compute partial derivatives of expressions.
The following snippet shows how to evaluate a string.
use exmex;
assert!((exmex::eval_str::<f64>("1.5 * ((cos(0) + 23.0) / 2.0)")? - 18.0).abs() < 1e-12);For floats, we have a list of predifined operators containing
^, *, /, +, -, sin, cos, tan, exp, log, and log2. The full list is
defined in DefaultOpsFactory. Library users can also create their
own operators as shown below in the section about extendability.
Variables
To define variables we can use strings that are not in the list of operators as shown in the following expression.
Additionally, variables should consist only of letters, numbers, and underscores. More precisely, they need to fit the
regular expression
r"^[a-zA-Z_]+[a-zA-Z_0-9]*".
Variables’ values are passed as slices to eval.
use exmex::prelude::*;
let to_be_parsed = "log(z) + 2* (-z^2 + sin(4*y))";
let expr = exmex::parse::<f64>(to_be_parsed)?;
assert!((expr.eval(&[3.7, 2.5])? - 14.992794866624788 as f64).abs() < 1e-12);The n-th number in the slice corresponds to the n-th variable. Thereby, the
alphatical order of the variables is relevant. In this example, we have y=3.7 and z=2.5.
If variables are between curly brackets, they can have arbitrary names, e.g.,
{456/549*(}, {x}, and confusingly even {x+y} are valid variable names as shown in the following.
use exmex::prelude::*;
let x = 2.1f64;
let y = 0.1f64;
let to_be_parsed = "log({x+y})"; // {x+y} is the name of one(!) variable 😕.
let expr = exmex::parse::<f64>(to_be_parsed)?;
assert!((expr.eval(&[x+y])? - 2.2f64.ln()).abs() < 1e-12);The value returned by parse implements the Express trait
and is an instance of the struct FlatEx.
Extendability
How to use custom operators as well as custom data types of the operands even with non-numeric literals is described in the following sub-sections.
Custom Operators
Operators are instances of the struct
Operator. An operator’s representation in the string-to-be-parsed is defined in the field
repr. Further, operator instances define a binary and a unary operator, since an operator
representation can correspond to both such as - or +. Note that we expect a unary operator to be always
on the left of a number.
To make serialization via serde possible, operators need to be created by factories as
shown in the following.
use exmex::prelude::*;
use exmex::{BinOp, MakeOperators, Operator, ops_factory};
ops_factory!(
IntegerOpsFactory, // name of the factory type
i32, // data type of the operands
Operator {
repr: "%",
bin_op: Some(BinOp{ apply: |a, b| a % b, prio: 1 }),
unary_op: None,
},
Operator {
repr: "/",
bin_op: Some(BinOp{ apply: |a, b| a / b, prio: 1 }),
unary_op: None,
}
);
let to_be_parsed = "19 % 5 / 2 / a";
let expr = FlatEx::<_, IntegerOpsFactory>::from_str(to_be_parsed)?;
assert_eq!(expr.eval(&[1])?, 2);To extend an existing list of operators, the macro ops_factory is not
sufficient. In this case one has to create a factory struct and implement the
MakeOperators trait with a little boilerplate code.
use exmex::prelude::*;
use exmex::{BinOp, DefaultOpsFactory, MakeOperators, Operator};
#[derive(Clone)]
struct ExtendedOpsFactory;
impl MakeOperators<f32> for ExtendedOpsFactory {
fn make<'a>() -> Vec<Operator<'a, f32>> {
let mut ops = DefaultOpsFactory::<f32>::make();
ops.push(
Operator {
repr: "invert",
bin_op: None,
unary_op: Some(|a: f32| 1.0 / a),
},
);
ops
}
}
let to_be_parsed = "1 / a + invert(a)";
let expr = FlatEx::<_, ExtendedOpsFactory>::from_str(to_be_parsed)?;
assert!((expr.eval(&[3.0])? - 2.0/3.0).abs() < 1e-12);Custom Data Types of Numbers
You can use any type that implements Copy and
FromStr. In case the representation of your data type in the
string does not match the number regex r"\.?[0-9]+(\.[0-9]+)?", you have to pass a
suitable regex and use the function
from_pattern instead of
from_str. Here is an example for bool.
use exmex::prelude::*;
use exmex::{BinOp, MakeOperators, Operator, ops_factory};
ops_factory!(
BooleanOpsFactory,
bool,
Operator {
repr: "&&",
bin_op: Some(BinOp{ apply: |a, b| a && b, prio: 1 }),
unary_op: None,
},
Operator {
repr: "||",
bin_op: Some(BinOp{ apply: |a, b| a || b, prio: 1 }),
unary_op: None,
},
Operator {
repr: "!",
bin_op: None,
unary_op: Some(|a| !a),
}
);
let to_be_parsed = "!(true && false) || (!false || (true && false))";
let expr = FlatEx::<_, BooleanOpsFactory>::from_pattern(to_be_parsed, "true|false")?;
assert_eq!(expr.eval(&[])?, true);Partial Derivatives
For default operators, expressions can be transformed into their partial derivatives
again represented by expressions. To this end, there exists the method partial.
use exmex::prelude::*;
let expr = exmex::parse::<f64>("x^2 + y^2")?;
let dexpr_dx = expr.clone().partial(0)?;
let dexpr_dy = expr.partial(1)?;
assert!((dexpr_dx.eval(&[3.0, 2.0])? - 6.0).abs() < 1e-12);
assert!((dexpr_dy.eval(&[3.0, 2.0])? - 4.0).abs() < 1e-12);Owned Expression
You cannot return all expression types from a function without a lifetime parameter.
For instance, expressions that are instances of FlatEx keep &strs instead of
Strings of variable or operator names to make faster parsing possible.
use exmex::prelude::*;
use exmex::ExResult;
fn create_expr<'a>() -> ExResult<FlatEx::<'a, f64>> {
// | |
// lifetime parameter necessary
let to_be_parsed = "log(z) + 2* (-z^2 + sin(4*y))";
exmex::parse::<f64>(to_be_parsed)
}
let expr = create_expr()?;
assert!((expr.eval(&[3.7, 2.5])? - 14.992794866624788 as f64).abs() < 1e-12);If you are willing to pay the price of roughly doubled parsing times, you can
obtain an expression that is an instance of OwnedFlatEx and owns
its strings. Evaluation times should be comparable. However, a lifetime parameter is
not needed anymore as shown in the following.
use exmex::{ExResult, Express, OwnedFlatEx};
fn create_expr() -> ExResult<OwnedFlatEx::<f64>> {
let to_be_parsed = "log(z) + 2* (-z^2 + sin(4*y))";
OwnedFlatEx::<f64>::from_str(to_be_parsed)
}
let expr_owned = create_expr()?;
assert!((expr_owned.eval(&[3.7, 2.5])? - 14.992794866624788 as f64).abs() < 1e-12);Priorities and Parentheses
In Exmex-land, unary operators always have higher priority than binary operators, e.g.,
-2^2=4 instead of -2^2=-4. Moreover, we are not too strict regarding parentheses.
For instance
use exmex;
assert_eq!(exmex::eval_str::<f64>("---1")?, -1.0);If you want to be on the safe side, we suggest using parentheses.
Display
An instance of FlatEx can be displayed as string. Note that this
unparsed string does not necessarily coincide with the original
string, since, e.g., curly brackets are added and expressions are compiled.
use exmex::prelude::*;
let expr = exmex::parse::<f64>("-sin(z)/cos(mother_of_names) + 2^7")?;
assert_eq!(format!("{}", expr), "-(sin({z}))/cos({mother_of_names})+128.0");Serialization and Deserialization
To use serde you can activate the feature serde.
The implementation un-parses and re-parses the whole expression.
Deserialize and
Serialize are implemented for
both, FlatEx and OwnedFlatEx.
Unicode
Unicode input strings are currently not supported 😕 but might be added in the future 😀.
Modules
Macros
This macro creates an operator factory struct that implements the trait
MakeOperators. You have to pass the name of the struct
as first, the type of the operands as seconds, and the Operators as
third to n-th argument.
Structs
A binary operator that consists of a function pointer and a priority.
Factory of default operators for floating point values.
This will be thrown at you if the parsing went wrong. Ok, obviously it is not an exception, so thrown needs to be understood figuratively.
This is the core data type representing a flattened expression and the result of
parsing a string. We use flattened expressions to make efficient evaluation possible.
Simplified, a flat expression consists of a SmallVec
of nodes and a SmallVec of operators that are applied
to the nodes in an order following operator priorities.
Operators can be custom-defined by the library-user in terms of this struct.
This is another representation of a flattened expression besides FlatEx.
The difference is that OwnedFlatEx can be used without
a lifetime parameter. All the data that FlatEx borrowed is kept in a
buffer by OwnedFlatEx. The drawback is that parsing takes longer, since
additional allocations are necessary. Evaluation time should be about the same for
FlatEx and OwnedFlatEx.
Traits
Expressions implementing this trait can be evaluated for specific variable values, derived partially, and unparsed, i.e., transformed into a string representation.
To use custom operators one needs to create a factory that implements this trait.
In this way, we make sure that we can deserialize expressions with
serde with the correct operators based on the type.
Functions
Parses a string, evaluates a string, and returns the resulting number.
Parses a string and returns the expression that can be evaluated.