src/tinyexprcpp/README.md
TinyExpr++ is a C++ version of the TinyExpr library.
TinyExpr++ is a very small recursive descent parser and evaluation engine for math expressions. It's handy when you want to add the ability to evaluation math expressions at runtime without adding a bunch of cruft to you project.
In addition to the standard math operators and precedence, TinyExpr++ also supports the standard C math functions and runtime binding of variables.
AVERAGE() and IF()).The following are changes from the original TinyExpr C library:
te_* functions are now wrapped in a te_parser class.te_interp(), te_compile(), and te_eval() have been replaced with te_parser::compile(), te_parser::evaluate(), and te_parser::set_vars().
set_vars() sets your list of custom functions and variables. compile() compiles and optimizes an expression.
Finally, evaluate() will use the already compiled expression and return its result.
evaluate() also has an overload that compiles and evaluates an expression in one call.TE_FUNCTION0) have been removed; types are now deduced by the compiler. The available flags
for variables and functions are now just combinations of TE_DEFAULT, TE_PURE, and TE_VARIADIC.TE_VARIADIC flag.
Refer to the AVERAGE() function in tinyexp.cpp.example4.cpp for a demonstration.te_expr is now a derivable base class. This means that you can derive from te_expr, add new fields to that derived class (e.g., arrays, strings, even other classes)
and then use a custom class as an argument to the various function types that accept a te_expr* parameter. The function that you connect can then dynamic_cast<>
this argument and use its custom fields, thus greatly enhancing the functionality for these types of functions.
Refer to the te_expr_array class in smoke.cpp for an example.compile and evaluate should be wrapped in try...catch blocks.te_parser class (you no longer need to call te_free). Also, replaced malloc/free with new/delete.std::variant (instead of unions) that support double, const double*, and 16 specific function pointer signatures.
Also uses std::initializer lists (instead of various pointer operations).te_expr and state's types and are more strongly typed.and: returns true if all conditions are true (accepts 1-7 arguments).average: returns the means for a range of values (accepts 1-7 arguments).cot: returns the cotangent of an angle.combin: alias for ncr(), like the Excel function.clamp: contrains a value to a range.fact: alias for fac(), like the Excel function.if: if a value is true, then returns second value; otherwise, returns third.max: returns the maximum of a range of values (accepts 1-7 arguments).min: returns the minimum of a range of values (accepts 1-7 arguments).mod: returns remainder from a division.or: returns true if any condition is true (accepts 1-7 arguments).not: returns logical negation of value.permut: alias for npr(), like the Excel function.power: alias for pow(), like the Excel function.rand: returns random number between 0 and 1.round: returns a number, rounded to a given decimal point. Decimal point is optional and defaults to 0.sign: returns the sign of a number: 1 if positive, -1 if negative, 0 if zero.sum: returns the sum of a list of values (accepts 1-7 arguments).sqr: returns a number squared.trunc: returns the integer part of a number.& logical AND.| logical OR.= equal to.<> not equal to.< less than.<= less than or equal to.> greater than.>= greater than or equal to.std::vector (which can be easily accessed and updated via the new get_vars()/set_vars() functions).is_function_used() and is_variable_used() functions to see if a specific function or variable was used in the last parsed formula.set_constant() function to find and update the value of a constant (custom) variable by name.get_constant() function to return the value of a constant (custom) variable by name.te_parser class and accessible via get_last_error_position().success() function to indicate if the last parse succeeded or not.get_result() function to get result from the last call to evaluate.std::numeric_limits for math constants (instead of macro constants).static_cast<>.constexprs and lambdas.std::lower_bound().nullptr (instead of 0).te_print() is now only available in debug builds.[[nodiscard]] attributes to improve compile-time warnings.constexpr and noexcept for C++ optimization.TinyExpr++ is self-contained in two files: tinyexpr.cpp and tinyexpr.h. To use
TinyExpr++, simply add those two files to your project.
Here is a minimal example to evaluate an expression at runtime.
#include "tinyexpr.h"
te_parser tep;
const char* c = "sqrt(5^2+7^2+11^2+(8-2)^2)";
const double r = tep.interpret("sqrt(5^2+7^2+11^2+(8-2)^2)");
printf("The expression:\n\t%s\nevaluates to:\n\t%f\n", c, r);
// prints 15.198684
TinyExpr++'s te_parser class defines these functions:
double interpret(const char* expression);
double get_result();
bool success();
int get_last_error_position();
set_vars(const std::vector<te_variable>& vars);
std::vector<te_variable>& get_vars();
get_decimal_separator();
get_list_separator();
interpret() takes an expression and immediately returns the result of it. If there
is a parse error, it returns NaN.
get_result() can be called anytime afterwards to retrieve the result from interpret().
success() can be called to see if the previous call interpret() succeeded or not.
If the parse failed, calling get_last_error_position() will return the 0-based index of where in the expression the parse failed.
example usage:
te_parser tep;
double a = tep.interpret("(5+5)"); /* Returns 10. */
double b = tep.interpret("(5+5)"); /* Returns 10, error is set to -1 (i.e., no error). */
double c = tep.interpret("(5+5"); /* Returns NaN, error is set to 3. */
Give set_vars() a list of constants, bound variables, and function pointers.
interpret() will then evaluate expressions using these variables and functions.
example usage:
#include "tinyexpr.h"
#include <stdio.h>
double x{0}, y{0};
// Store variable names and pointers.
te_parser tep;
tep.set_vars({{"x", &x}, {"y", &y}});
// Compile the expression with variables.
auot result = tep.interpret("sqrt(x^2+y^2)");
if (tep.success()) {
x = 3; y = 4;
const double h1 = tep.interpret(); /*Will use the previously used expression, returns 5. */
x = 5; y = 12;
const double h2 = tep.interpret(); /* Returns 13. */
} else {
printf("Parse error at %d\n", tep.get_last_error_position());
}
Here is a complete example that will evaluate an expression passed in from the command
line. It also does error checking and binds the variables x and y to 3 and 4, respectively.
#include "tinyexpr.h"
#include <stdio.h>
int main(int argc, char *argv[])
{
if (argc < 2) {
printf("Usage: example2 \"expression\"\n");
return 0;
}
const char *expression = argv[1];
printf("Evaluating:\n\t%s\n", expression);
/* This shows an example where the variables
* x and y are bound at eval-time. */
double x{0}, y{0};
// Store variable names and pointers.
te_parser tep;
tep.set_vars({{"x", &x}, {"y", &y}});
/* This will compile the expression and check for errors. */
auto result = tep.interpret(expression);
if (tep.success()) {
/* The variables can be changed here, and eval can be called as many
* times as you like. This is fairly efficient because the parsing has
* already been done. */
x = 3; y = 4;
const double r = tep.interpret();
printf("Result:\n\t%f\n", r);
} else {
/* Show the user where the error is at. */
printf("\t%*s^\nError near here", tep.get_last_error_position(), "");
}
return 0;
}
This produces the output:
$ example2 "sqrt(x^2+y2)"
Evaluating:
sqrt(x^2+y2)
^
Error near here
$ example2 "sqrt(x^2+y^2)"
Evaluating:
sqrt(x^2+y^2)
Result:
5.000000
TinyExpr++ can also call to custom functions implemented in C. Here is a short example:
double my_sum(double a, double b) {
/* Example C function that adds two numbers together. */
return a + b;
}
te_parser tep;
tep.set_vars({
{"mysum", my_sum, TE_FUNCTION2} /* TE_FUNCTION2 used because my_sum takes two arguments. */
};)
const double r = tep.interpret("mysum(5, 6)");
TinyExpr++ supports other locales and non-US formatted formulas. Here is an example:
#include "tinyexpr.h"
#include <cstdio>
#include <locale>
#include <clocale>
int main(int argc, char *argv[])
{
/* Set locale to German.
This string is platform dependent. The following works on Windows,
consult your platform's documentation for more details.*/
setlocale(LC_ALL, "de-DE");
std::locale::global(std::locale("de-DE"));
/* After setting your locale to German, functions like strtod() will fail
with values like "3.14" because it expects "3,14" instead.
To fix this, we will tell the parser to use "," as the decimal separator
and ";" as list argument separator.*/
const char *expression = "pow(2,2; 2)"; // instead of "pow(2.2, 2)"
printf("Evaluating:\n\t%s\n", expression);
te_parser tep;
tep.set_decimal_separator(',');
tep.set_list_separator(';');
/* This will compile the expression and check for errors. */
auto r = tep.interpret(expression);
if (tep.success()) {
const double r = tep.interpret(expression); printf("Result:\n\t%f\n", r);
} else {
/* Show the user where the error is at. */
printf("\t%*s^\nError near here", tep.get_last_error_position(), "");
}
return 0;
}
This produces the output:
$ example4
Evaluating:
pow(2,2; 2)
Result:
4,840000
te_parser::interpret() uses a simple recursive descent parser to compile your
expression into a syntax tree. For example, the expression "sin x + 1/4"
parses as:
te_parser::interpret() also automatically prunes constant branches. In this example,
the compiled expression returned by te_compile() would become:
TinyExpr++ is fairly fast compared to C when the expression is short, when the
expression does hard calculations (e.g. exponentiation), and when some of the
work can be simplified by interpret(). TinyExpr++ is slow compared to C when the
expression is long and involves only basic arithmetic.
Here is some example performance numbers taken from the included benchmark.cpp program:
| Expression | interpret time | native C time | slowdown |
|---|---|---|---|
| sqrt(a^1.5+a^2.5) | 16,363 ms | 13,193 ms | 24.03% slower |
| a+5 | 3,051 ms | 1,255 ms | 143.11% slower |
| a+(5*2) | 1,754 ms | 524 ms | 234.73% slower |
| (a+5)*2 | 3,225 ms | 518 ms | 522.59% slower |
| (1/(a+1)+2/(a+2)+3/(a+3)) | 12,754 ms | 680 ms | 1,775.59% slower |
Note that TinyExpr++ is slower compared to TinyExpr because of additional type safety checks.
TinyExpr++ parses the following grammar:
<list> = <expr> {"," <expr>}
<expr> = <term> {("+" | "-") <term>}
<term> = <factor> {("*" | "/" | "%") <factor>}
<factor> = <power> {"^" <power>}
<power> = {("-" | "+")} <base>
<base> = <constant>
| <variable>
| <function-0> {"(" ")"}
| <function-1> <power>
| <function-X> "(" <expr> {"," <expr>} ")"
| "(" <list> ")"
In addition, whitespace between tokens is ignored.
Valid variable names consist of a lower case letter followed by any combination of: lower case letters a through z, the digits 0 through 9, and underscore. Constants can be integers, decimal numbers, or in scientific notation (e.g. 1e3 for 1000). A leading zero is not required (e.g. .5 for 0.5)
TinyExpr++ supports addition (+), subtraction/negation (-), multiplication (*), division (/), exponentiation (^) and modulus (%) with the normal operator precedence (the one exception being that exponentiation is evaluated left-to-right, but this can be changed - see below).
The following C math functions are also supported:
The following functions are also built-in and provided by TinyExpr++:
fac 5 == 120)ncr(6,2) == 15)npr(6,2) == 30)Also, the following constants are available:
pi, eBy default, TinyExpr++ does exponentiation from left to right. For example:
a^b^c == (a^b)^c and -a^b == (-a)^b
This is by design. It's the way that spreadsheets do it (e.g. Excel, Google Sheets).
If you would rather have exponentiation work from right to left, you need to
define TE_POW_FROM_RIGHT when compiling tinyexpr.c. There is a
commented-out define near the top of that file. With this option enabled, the
behaviour is:
a^b^c == a^(b^c) and -a^b == -(a^b)
That will match how many scripting languages do it (e.g. Python, Ruby).
Also, if you'd like log to default to the natural log instead of log10,
then you can define TE_NAT_LOG.