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 Error;
#
For floats, we have a list of predifined operators containing
^
, *
, /
, +
, -
, sin
, cos
, tan
, exp
, log
, and log2
. The full list is
defined in DefaultOpsFactory
. Further, the constants π and Euler's number can be
used via PI
and E
, respectively. 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, 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 Error;
#
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 Error;
#
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 and Constants
Operators are instances of the struct
Operator
. Constants are also 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 Error;
#
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 Error;
#
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 parse
or
from_str
. Here is an example for bool
.
# use Error;
#
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 Error;
#
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 Error;
#
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 Error;
#
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 Error;
#
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 Error;
#
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 😀.