# Crate exmex

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`, `log10`, `ln`, and `log2`. Further, the constants π, τ, and Euler’s number are refered to via `π`/`PI`, `τ/TAU`, 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 = "α * ln(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 = "ln({👍+👎})";  // {👍+👎} 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` if the feature `partial` is not used.

### Features

Exmex comes with three features that can be activated in the `Cargo.toml` via

``````[dependencies]
exmex = { ..., features = ["partial", "serde", "value"] }``````

`partial` allows the computation of partal derivatives, `serde` enables serialization and deserialization, and `value` makes a more general value type accessible.

#### Partial Derivatives

Expressions with floating point data types can be transformed into their partial derivatives again represented by expressions after activating the feature `partial`. See the readme for examples.

#### 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 `FlatEx`.

#### A more General Value Type

To use different data types within an expression, one can activate the feature `value` and use the more general type `Val`. The additional flexibility comes with higher parsing and evaluation run times, see the benchmarks.

### 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 can be accessed via the method `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` or `sin(4)`. Note that `sin4` is parsed as variable name, but `sin 4` is equivalent to `sin(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)` or `4 + E`. Note that the calling notation of constant operators such as `PI()` 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(&)?, 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’s literals in the string does not match the number regex `r"^(\.?[0-9]+(\.[0-9]+)?)"`, you have to create a suitable matcher type that implements `MatchLiteral`. Given a suitable regex pattern, you can utilize the macro `literal_matcher_from_pattern`. Here is an example for `bool`.

``````use exmex::prelude::*;
use exmex::{
BinOp, MakeOperators, MatchLiteral, Operator,
literal_matcher_from_pattern, 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)
);
literal_matcher_from_pattern!(BooleanMatcher, "^(true|false)");
let to_be_parsed = "!(true && false) || (!false || (true && false))";
type FlatExBool = FlatEx::<bool, BooleanOpsFactory, BooleanMatcher>;
let expr = FlatExBool::from_str(to_be_parsed)?;
assert_eq!(expr.eval(&[])?, true);``````

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

Expressions can be displayed as string. This `unparse`d string coincides with the original string.

``````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) + 2^7 + E");``````

## Modules

Exmex’ prelude can be imported via `use exmex::prelude::*;`.

## Macros

Creates an `ExError` with a formatted message.

Helper to implement a struct called `\$matcher_name` that implements `MatchLiteral` and matches the regex pattern `\$regex_pattern`.

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.

Default factory to match numeric literals.

Operators can be unary such as `sin`, binary such as `*`, unary and binary such as `-`, or constants such as `π`. To use custom operators, see also the macro `ops_factory`.

Literal matcher type that was created with the macro `literal_matcher_from_pattern`.

`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 is a parse function `parse_val`. 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

`feature = "partial"` - Trait for partial differentiation.

Expressions implementing this trait can be parsed from stings, evaluated for specific variable values, 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.

Implement this trait to create a matcher for custom literals of operands.

## 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 `FlatExVal` with datatype `Val`.

## Type Definitions

Exmex’ result type with `ExError` as error type.

`feature = "value"` - Alias for `FlatEx` with `Val` as data type and `ValOpsFactory` as operator factory.