Crate exmex[−][src]
Expand description
Exmex is an extendable mathematical expression parser and evaluator. Ease of use, flexibility, and efficient evaluations are its main design goals.
Exmex can parse mathematical expressions possibly containing variables and operators. On the one hand, it comes with a list of default operators
for floating point values. For differentiable default operators, Exmex can compute partial derivatives. On the other hand, users can define their
own operators and work with different data types such as float, integer, bool, or other types that implement Clone
, FromStr
, and Debug
.
The following snippet shows how to evaluate a string.
use exmex;
let eval_result = exmex::eval_str::<f64>("1.5 * ((cos(2*π) + 23.0) / 2.0)")?;
assert!((eval_result - 18.0).abs() < 1e-12);
For floats, we have a list of predifined operators containing
^
, *
, /
, +
, -
, sin
, cos
, tan
, exp
, log
, and log2
. Further, the constants π
and Euler’s number can be used via π
/PI
and E
, respectively. The full list is
defined in FloatOpsFactory
. Library users can also create their
own operators and constants 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, greek letters, numbers, and underscores. More precisely, they
need to fit the regular expression r"[a-zA-Zα-ωΑ-Ω_]+[a-zA-Zα-ωΑ-Ω_0-9]*"
, if they are not between curly brackets.
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, 1.0])? - 14.992794866624788 as f64).abs() < 1e-12);
The n
-th number in the slice corresponds to the n
-th variable. Thereby, the
alphabetical order of the variables is relevant. More precisely, the order is defined by the way how Rust sorts strings.
In the example above we have y=3.7
, z=2.5
, and α=1
. Note that α
is the Greek letter Alpha.
If variables are between curly brackets, they can have arbitrary names, e.g.,
{456/549*(}
, {x}
, and also {👍+👎}
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({👍+👎})"; // {👍+👎} 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
is an instance of the struct FlatEx
that implements the Express
trait. Moreover, FlatEx
and
Express
are the only items made accessible by the wildcard import from
prelude
.
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 &str
s instead of
String
s 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);
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 and Constants
Operators are instances of the struct
Operator
. Constants are defined in terms of constant operators. More precisely,
operators can be
- binary such as
*
, - unary such as
sin
, - binary as well as unary such as
-
, or - constant such as
PI
.
An operator’s representation is defined in the field
repr
. A token of the string-to-be-parsed is identified as operator if it matches the operator’s
representation exactly. For instance, PI
will be parsed as the constant π while PI5
will be parsed as a variable with name PI5
.
When an operator’s representation is used in a string-to-be-parsed, the following applies:
- Binary operators are positioned between their operands, e.g.,
4 ^ 5
. - Unary operators are positioned in front of their operands, e.g.,
-1
orsin(4)
. Note thatsin4
is parsed as variable name, butsin 4
is equivalent tosin(4)
. - Constant operators are handled as if they were numbers and are replaced by their numeric values during parsing.
They can be used as in
sin(PI)
or4 + E
. Note that the calling notation of constant operators such asPI()
is invalid.
Binary, unary, and constant operators can be created with the functions make_bin
, make_unary
,
and make_constant
, respectively.
Operators need to be created by factories to make serialization via serde
possible 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::make_bin(
"%",
BinOp{
apply: |a, b| a % b,
prio: 1,
is_commutative: false,
}
),
Operator::make_bin(
"/",
BinOp{
apply: |a, b| a / b,
prio: 1,
is_commutative: false,
}
),
Operator::make_constant("TWO", 2)
);
let to_be_parsed = "19 % 5 / TWO / 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::{FloatOpsFactory, MakeOperators, Operator};
#[derive(Clone)]
struct ExtendedOpsFactory;
impl MakeOperators<f32> for ExtendedOpsFactory {
fn make<'a>() -> Vec<Operator<'a, f32>> {
let mut ops = FloatOpsFactory::<f32>::make();
ops.push(
Operator::make_unary("invert", |a| 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 Clone
,
FromStr
, and Debug
. 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 parse
or
from_str
. Here is an example for bool
.
use exmex::prelude::*;
use exmex::{BinOp, MakeOperators, Operator, ops_factory};
ops_factory!(
BooleanOpsFactory,
bool,
Operator::make_bin(
"&&",
BinOp{
apply: |a, b| a && b,
prio: 1,
is_commutative: true,
}
),
Operator::make_bin(
"||",
BinOp{
apply: |a, b| a || b,
prio: 1,
is_commutative: true,
}
),
Operator::make_unary("!", |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);
You can also pre-compile the regex and use Express::from_regex
.
Two examples of exmex with non-trivial data types are:
- Numbers can be operators and operators can operate on operators, see, e.g., also a blog post on ninety.de.
- The value type implemented as part of the feature
value
allows expressions containing integers, floats, and bools. Therewith, Pythonesque expressions of the form"x if a > b else y"
are possible.
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
Instances of FlatEx
and OwnedFlatEx
can be displayed as string. Note that this
unparse
d string does not necessarily coincide with the original
string, since, e.g., curly brackets are added, expressions are compiled, and constants are
replaced by their numeric values during parsing.
use exmex::prelude::*;
let expr = exmex::parse::<f64>("-sin(z)/cos(mother_of_names) + 2^7 + E")?;
assert_eq!(format!("{}", expr), "-(sin({z}))/cos({mother_of_names})+130.71828182845906");
Features
Exmex comes with two features that can be activated in the Cargo.toml
via
[dependencies]
exmex = { ..., features = ["serde", "value"] }
serde
enables serialization and deserialization and value
a more general value type.
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
.
A more General Value Type
To use different data types within an expression, one can activate the feature value
. The additional
flexibility comes with higher parsing (factor 1.1-1.4) and evaluation run times (factor 2-3).
Modules
Macros
Creates an ExError
with formatted message.
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 second, and the Operator
s as
third to n-th argument.
Structs
A binary operator that consists of a function pointer, a priority, and a commutativity-flag.
This will be thrown at you if the somehting within Exmex 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.
Factory of default operators for floating point values.
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
.
feature = "value"
- Factory of default operators for the data type Val
.
Enums
feature = "value"
-
The value type Val
can contain an integer, float, bool, none, or error.
To use the value type, there are the separate parse functions parse_val
and
parse_val_owned
that wrap Express::from_regex
and use the corresponding operator factory ValOpsFactory
. In the following example,
the ternary Python-style a if condition else b
is used. This is equivalent to if condition {a} else {b}
in Rust
or condition ? a : b
in C.
Traits
Expressions implementing this trait can be evaluated for specific variable values, differentiated 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 the expression, and returns the resulting number.
Parses a string and returns the expression that can be evaluated.
feature = "value"
- Parses a string into an expression of type OwnedFlatExVal
with
datatype Val
.
Type Definitions
feature = "value"
- Alias for FlatEx
with Val
as data type and ValOpsFactory
as operator factory.
feature = "value"
- Alias for OwnedFlatEx
with Val
as data type and ValOpsFactory
as operator factory.