Authors: Juha Nieminen (http://iki.fi/warp/), Joel Yliluoma (http://iki.fi/bisqwit/).
The usage license of this library is located at the end of this file.
What's new in v3.3.2
What's new in v3.3.1
What's new in v3.3
Parse()
method now performs more exhaustive constant
folding (calculating constant expressions at parse time) than before.
Also integral powers (eg. like "x^4"
) are now more optimized
at parse time, resulting in faster evaluation even without a call to the
Optimize()
method (although the latter will sometimes still
result in an even better result). The speed impact of this on the
Parse()
method has been kept minimal.
Optimize()
method significantly faster than in the previous version. Also new and
more exhaustive rules have been added, resulting in better results in
certain cases (eg. when using basic operators in very complex functions).
Often people need to ask some mathematical expression from the user and then evaluate values for that expression. The simplest example is a program which draws the graphic of a user-defined function on screen.
This library adds C-style function string parsing to the program. This
means that you can evaluate the string "sqrt(1-x^2+y^2)"
with
given values of 'x
' and 'y
'.
The library is intended to be very fast. It byte-compiles the function string at parse time and interpretes this byte-code at evaluation time. The evaluation is straightforward and no recursions are done (uses stack arithmetic).
Empirical tests show that it indeed is very fast (specially compared to libraries which evaluate functions by just interpreting the raw function string).
The library is made in ISO C++ and requires a standard-conforming C++ compiler.
To use the FunctionParser
class, you have to include
"fparser.hh"
in your source code files which use the
FunctionParser
class.
When compiling, you have to compile fparser.cc
and
fpoptimizer.cc
and link them to the main program. In some
developement environments it's enough to add those two files to your
current project (usually header files don't have to be added to the
project for the compilation to work).
If you are not going to use the optimizer (ie. you have commented out
FP_SUPPORT_OPTIMIZER
in fpconfig.hh
), you can
leave the latter file out.
There is a set of precompiler options in the fpconfig.hh
file
which can be used for setting certain features on or off. All of these options
can also be specified from the outside, using precompiler settings (eg. the
-D
option in gcc), and thus it's not necessary to modify this
file.
FP_SUPPORT_TR1_MATH_FUNCS
: (Default off)
Define this precompiler constant to make the library use additional math functions defined in the C99 standard and the C++ TR1 standard proposal (but not yet in the official C++ standard). This can make evaluation faster when these functions are involved.
The C++ TR1 math functions in question are: asinh()
,
acosh()
, atanh()
, exp2()
and
log2()
.
FP_ENABLE_EVAL
: (Default off)
Even though the maximum recursion level of the eval()
function is limited, it is still possible to write functions which never
reach this maximum recursion level but take enormous amounts of
time to evaluate (this can be undesirable eg. in web server-side
applications). For this reason this function is disabled by default.
You can add support for the eval()
function by
defining this precompiler constant.
FP_EVAL_MAX_REC_LEVEL
: (Default 1000)
Sets the maximum recursion level allowed for eval()
.
FP_SUPPORT_OPTIMIZER
: (Default on)
If you are not going to use the Optimize()
method, you
can comment this line out to speed-up the compilation a bit, as
well as making the binary a bit smaller. (Optimize()
can
still be called, but it will not do anything.)
You can also disable the optimizer by specifying the
FP_NO_SUPPORT_OPTIMIZER
precompiler constant in your
compiler settings.
FP_EPSILON
: (Default 1e-14
)
Epsilon value used in comparison operators. If this line is commented out, then no epsilon will be used.
FP_USE_THREAD_SAFE_EVAL
: (Default off)
Define this precompiler constant to make Eval()
thread-safe. Refer to the thread safety
section later in this document for more information.
Note that defining this may make Eval()
slightly slower.
FP_USE_THREAD_SAFE_EVAL_WITH_ALLOCA
: (Default off)
This is like the previous, but makes Eval()
use the
alloca()
function (instead of std::vector
).
This will make it faster, but the alloca()
function is not standard and thus not supported by all compilers.
FP_NO_EVALUATION_CHECKS
: (Default off)
If this precompiler constant is defined, no evaluation-time checks will be performed. This may give a slight boost in speed in certain situations. Consult the evaluation checks section below for more information on this subject.
The class implements a safe copy constructor and assignment operator.
It uses the copy-on-write technique for efficiency. This means that when copying or assigning a FunctionParser instance, the internal data (which in some cases can be quite lengthy) is not immediately copied but only when the contents of the copy (or the original) are changed.
This means that copying/assigning is a very fast operation, and if the copies are never modified then actual data copying never happens either.
The Eval()
and EvalError()
methods of the
copy can be called without the internal data being copied.
Calling Parse()
, Optimize()
or the user-defined
constant/function adding methods will cause a deep-copy.
An identifier is a function (internal or user-defined), variable, constant or unit. New identifiers can be specified with the functions described in the next subsections.
The name of an identifier can use any alphanumeric characters, the underscore character and any UTF8-encoded unicode character. The first character of the name cannot be a numeric digit, though.
All functions, variables, constants and units must use unique names. It's not possible to add two different identifiers with the same name.
int Parse(const std::string& Function, const std::string& Vars, bool useDegrees = false); int Parse(const char* Function, const std::string& Vars, bool useDegrees = false);
Parses the given function and compiles it to internal format. Return value is -1 if successful, else the index value to the location of the error.
void setDelimiterChar(char);
Sets an ending delimiter character for the function string. (See the long description for more details.)
const char* ErrorMsg(void) const;
Returns an error message corresponding to the error in
Parse()
, or an empty string if no such error occurred.
ParseErrorType GetParseErrorType() const;
Returns the type of parsing error which occurred. Possible return types are described in the long description.
double Eval(const double* Vars);
Evaluates the function given to Parse()
.
int EvalError(void) const;
Returns 0
if no error happened in the previous call to
Eval()
, else an error code >0
.
void Optimize();
Tries to optimize the bytecode for faster evaluation.
bool AddConstant(const std::string& name, double value);
Add a constant to the parser. Returns false
if the name of
the constant is invalid, else true
.
bool AddUnit(const std::string& name, double value);
Add a new unit to the parser. Returns false
if the name of
the unit is invalid, else true
.
bool AddFunction(const std::string& name, double (*functionPtr)(const double*), unsigned paramsAmount);
Add a user-defined function to the parser (as a function pointer).
Returns false
if the name of the function is invalid, else
true
.
bool AddFunction(const std::string& name, FunctionParser&);
Add a user-defined function to the parser (as a FunctionParser
instance). Returns false
if the name of the function is invalid,
else true
.
bool RemoveIdentifier(const std::string& name);
Removes the constant, unit or user-defined function with the specified name from the parser.
int ParseAndDeduceVariables(const std::string& function, int* amountOfVariablesFound = 0, bool useDegrees = false); int ParseAndDeduceVariables(const std::string& function, std::string& resultVarString, int* amountOfVariablesFound = 0, bool useDegrees = false); int ParseAndDeduceVariables(const std::string& function, std::vector<std::string>& resultVars, bool useDegrees = false);
Like Parse()
, but the variables in the function are deduced
automatically. The amount of found variables and the variable names themselves
are returned by the different versions of the function.
int Parse(const std::string& Function, const std::string& Vars, bool useDegrees = false); int Parse(const char* Function, const std::string& Vars, bool useDegrees = false);
Parses the given function (and compiles it to internal format).
Destroys previous function. Following calls to Eval()
will evaluate
the given function.
The strings given as parameters are not needed anymore after parsing.
Parameters:
Function |
String containing the function to parse. |
Vars |
String containing the variable names, separated by commas. Eg. "x,y" , "VarX,VarY,VarZ,n" or
"x1,x2,x3,x4,__VAR__" .
|
useDegrees |
(Optional.) Whether to use degrees or radians in trigonometric functions. (Default: radians) |
If a char*
is given as the Function
parameter,
it must be a null-terminated string.
Variables can have any size and they are case sensitive (ie.
"var"
, "VAR"
and "Var"
are
different variable names). Letters, digits, underscores and
UTF8-encoded characters can be used in variable names, but the name of
a variable can't begin with a digit. Each variable name can appear only
once in the 'Vars
' string. Function names are not legal
variable names.
Using longer variable names causes no overhead whatsoever to the
Eval()
method, so it's completely safe to use variable names
of any size.
The third, optional parameter specifies whether angles should be interpreted as radians or degrees in trigonometrical functions. If not specified, the default value is radians.
Return values:
-1
.
0
is the first character, 1
the second, etc).
If the error was not a parsing error returns an index to the end of the
string.
Example: parser.Parse("3*x+y", "x,y");
void setDelimiterChar(char);
By default the parser expects the entire function string to be valid
(ie. the entire contents of the given std::string
, or a C string
ending in the null character '\0'
).
If a delimiter character is specified with this function, then if it's
encountered at the outermost parsing level by the Parse()
function, and the input function has been valid so far, Parse()
will return an index to this character inside the input string, but rather
than set an error code, FP_NO_ERROR
will be set.
The idea is that this can be used to more easily parse functions which are embedded inside larger strings, containing surrounding data, without having to explicitly extract the function to a separate string.
For example, suppose you are writing an interpreter for a scripting language, which can have commands like this:
let MyFunction(x,y) = { sin(x*x+y*y) } // A 2-dimensional function
Normally when parsing such a line you would have to extract the part
inside the curly brackets into a separate string and parse it that way.
With this feature what you can do instead is to set '}'
as
the delimiter character and then simply give a pointer to the character
which comes after the '{'
. If all goes well, the
Parse()
function will return an index to the '}'
character (from the given starting point) and GetParseErrorType()
will return FP_NO_ERROR
. You can use the return
value (if it's not -1
) to jump forward in the string to the
delimiter character.
Note that a null character ('\0'
) or the end of the
std::string
(if one was given) will still be a valid end of
the function string even if a delimiter character was specified. (In this
case Parse()
will return -1
if there was no error,
as usual.)
Also note that the delimiter character cannot be any valid operator
or alphanumeric (including the underscore) character, nor the other
characters defined in the function syntax. It must be a character not
supported by the function parser (such as '}'
,
'"'
, ']'
, etc).
const char* ErrorMsg(void) const;
Returns a pointer to an error message string corresponding to the error
caused by Parse()
(you can use this to print the proper error
message to the user). If no such error has occurred, returns an empty string.
ParseErrorType GetParseErrorType() const;
Returns the type of parse error which occurred.
This method can be used to get the error type if ErrorMsg()
is not enough for printing the error message. In other words, this can be
used for printing customized error messages (eg. in another language).
If the default error messages suffice, then this method doesn't need
to be called.
FunctionParser::ParseErrorType
is an enumerated type inside
the class (ie. its values are accessed like
"FunctionParser::SYNTAX_ERROR
").
The possible values for FunctionParser::ParseErrorType are listed below,
along with their equivalent error message returned by the
ErrorMsg()
method:
FP_NO_ERROR |
If no error occurred in the previous call to Parse() . |
SYNTAX_ERROR |
"Syntax error" |
MISM_PARENTH |
"Mismatched parenthesis" |
MISSING_PARENTH |
"Missing ')'" |
EMPTY_PARENTH |
"Empty parentheses" |
EXPECT_OPERATOR |
"Syntax error: Operator expected" |
OUT_OF_MEMORY |
"Not enough memory" |
UNEXPECTED_ERROR |
"An unexpected error occurred. Please make a full bug report to the author" |
INVALID_VARS |
"Syntax error in parameter 'Vars' given to FunctionParser::Parse()" |
ILL_PARAMS_AMOUNT |
"Illegal number of parameters to function" |
PREMATURE_EOS |
"Syntax error: Premature end of string" |
EXPECT_PARENTH_FUNC |
"Syntax error: Expecting ( after function" |
NO_FUNCTION_PARSED_YET |
"(No function has been parsed yet)" |
double Eval(const double* Vars);
Evaluates the function given to Parse()
.
The array given as parameter must contain the same amount of values as
the amount of variables given to Parse()
. Each value corresponds
to each variable, in the same order.
Return values:
Parse()
.
Example:
double Vars[] = {1, -2.5};
double result = parser.Eval(Vars);
int EvalError(void) const;
Used to test if the call to Eval()
succeeded.
Return values:
If there was no error in the previous call to Eval()
,
returns 0
, else returns a positive value as follows:
eval()
reached
void Optimize();
This method can be called after calling the Parse()
method.
It will try to simplify the internal bytecode so that it will evaluate faster
(it tries to reduce the amount of opcodes in the bytecode).
For example, the bytecode for the function "5+x*y-25*4/8"
will
be reduced to a bytecode equivalent to the function "x*y-7.5"
(the
original 11 opcodes will be reduced to 5). Besides calculating constant
expressions (like in the example), it also performs other types of
simplifications with variable and function expressions.
This method is quite slow and the decision of whether to use it or
not should depend on the type of application. If a function is parsed
once and evaluated millions of times, then calling Optimize()
may speed-up noticeably. However, if there are tons of functions to parse
and each one is evaluated once or just a few times, then calling
Optimize()
will only slow down the program.
Also, if the original function is expected to be optimal, then calling
Optimize()
would be useless.
Note: Currently this method does not make any checks (like
Eval()
does) and thus things like "1/0"
will cause
undefined behaviour. (On the other hand, if such expression is given to the
parser, Eval()
will always give an error code, no matter what
the parameters.) If caching this type of errors is important, a work-around
is to call Eval()
once before calling Optimize()
and checking EvalError()
.
If the destination application is not going to use this method,
the compiler constant FP_SUPPORT_OPTIMIZER
can be undefined in
fpconfig.hh
to make the library smaller (Optimize()
can still be called, but it will not do anything).
(If you are interested in seeing how this method optimizes the opcode,
you can call the PrintByteCode()
method before and after the
call to Optimize()
to see the difference.)
bool AddConstant(const std::string& name, double value);
This method can be used to add constants to the parser. Syntactically constants are identical to variables (ie. they follow the same naming rules and they can be used in the function string in the same way as variables), but internally constants are directly replaced with their value at parse time.
Constants used by a function must be added before calling
Parse()
for that function. Constants are preserved between
Parse()
calls in the current FunctionParser instance, so
they don't need to be added but once. (If you use the same constant in
several instances of FunctionParser, you will need to add it to all the
instances separately.)
Constants can be added at any time and the value of old constants can
be changed, but new additions and changes will only have effect the next
time Parse()
is called. (That is, changing the value of a constant
after calling Parse()
and before calling Eval()
will have no effect.)
The return value will be false
if the 'name
' of
the constant was illegal, else true
. If the name was illegal,
the method does nothing.
Example: parser.AddConstant("pi", 3.1415926535897932);
Now for example parser.Parse("x*pi", "x");
will be identical
to the call parser.Parse("x*3.1415926535897932", "x");
bool AddUnit(const std::string& name, double value);
In some applications it is desirable to have units of measurement. A typical example is an application which creates a page layout to be printed. When printing, distances are usually measured in points (defined by the resolution of the printer). However, it is often more useful for the user to be able to specify measurements in other units such as centimeters or inches.
A unit is simply a value by which the preceding element is multiplied.
For example, if the printing has been set up to 300 DPI, one inch is
then 300 points (dots). Thus saying eg. "5in"
is the same as saying
"5*300"
or "1500"
(assuming "in"
has
been added as a unit with the value 300).
Note that units are slightly different from a multiplication in
that they have a higher precedence than any other operator (except
parentheses). Thus for example "5/2in"
is parsed as
"5/(2*300)"
.
(If 5/2 inches is what one wants, it has to be written "(5/2)in"
.)
You can use the AddUnit()
method to add a new unit. The
unit can then be used after any element in the function (and will work as
a multiplier for that element). An element is a float literal, a constant,
a variable, a function or any expression in parentheses. When the element
is not a float literal nor an expression in parentheses, there has to naturally
be at least one whitespace between the element and the unit (eg.
"x in"
). To change the value of a unit, call
AddUnit()
again with the same unit name and the new value.
Unit names share the same namespace as constants, functions and variables, and thus should be distinct from those.
Example: parser.AddUnit("in", 300);
Now for example the function "5in"
will be identical to
"(5*300)"
. Other usage examples include "x in"
,
"3in+2"
, "pow(x,2)in"
, "(x+2)in"
.
bool AddFunction(const std::string& name, double (*functionPtr)(const double*), unsigned paramsAmount);This method can be used to add new functions to the parser. For example, if you would like to add a function "
sqr(A)
" which squares the
value of A
, you can do it with this method (so that you don't
need to touch the source code of the parser).
The method takes three parameters:
double functionName(const double* params);
double*
it gets as a parameter).
The return value will be false
if the given name was invalid
(either it did not follow the variable naming conventions, or the name was
already reserved), else true
. If the return value is
false
, nothing is added.
Example: Suppose we have a C++ function like this:
double Square(const double* p)
{
return p[0]*p[0];
}
Now we can add this function to the parser like this:
parser.AddFunction("sqr", Square, 1);
parser.Parse("2*sqr(x)", "x");
An example of a useful function taking no parameters is a function returning a random value. For example:
double Rand(const double*)
{
return drand48();
}
parser.AddFunction("rand", Rand, 0);
Important note: If you use the Optimize()
method,
it will assume that the user-given function has no side-effects, that is,
it always returns the same value for the same parameters. The optimizer will
optimize the function call away in some cases, making this assumption.
(The Rand()
function given as example above is one such
problematic case.)
bool AddFunction(const std::string& name, FunctionParser&);
This method is almost identical to the previous AddFunction()
,
but instead of taking a C++ function, it takes another FunctionParser
instance.
There are some important restrictions on making a FunctionParser instance call another:
Parse()
call before giving it as parameter. That
is, if you want to use the parser A
in the parser
B
, you must call A.Parse()
before you can
call B.AddFunction("name", A)
.
AddFunction()
of another instance. Changing the number of variables will result in
malfunction.
AddFunction()
will fail (ie. return false
)
if a recursive loop is
formed. The method specifically checks that no such loop is built.
Example:
FunctionParser f1, f2;
f1.Parse("x*x", "x");
f2.AddFunction("sqr", f1);
This version of the AddFunction()
method can be useful to
eg. chain user-given functions. For example, ask the user for a function F1,
and then ask the user another function F2, but now the user can
call F1 in this second function if he wants (and so on with a third
function F3, where he can call F1 and F2, etc).
bool RemoveIdentifier(const std::string& name);
If a constant, unit or user-defined function with the specified name
exists in the parser, it will be removed and the return value will be
true
, else nothing will be done and the return value will be
false
.
(Note: If you want to remove everything from an existing
FunctionParser instance, simply assign a fresh instance to it, ie. like
"parser = FunctionParser();
")
int ParseAndDeduceVariables(const std::string& function, int* amountOfVariablesFound = 0, bool useDegrees = false); int ParseAndDeduceVariables(const std::string& function, std::string& resultVarString, int* amountOfVariablesFound = 0, bool useDegrees = false); int ParseAndDeduceVariables(const std::string& function, std::vector<std::string>& resultVars, bool useDegrees = false);
These functions work in the same way as the Parse()
function,
but the variables in the input function string are deduced automatically. The
parameters are:
function
: The input function string, as with
Parse()
.
amountOfVariablesFound
: If non-null, the amount of found
variables will be assigned here.
resultVarString
: The found variables will be written to
this string, in the same format as accepted by the Parse()
function. The variable names will be sorted using the <
operator of std::string
.
resultVars
: The found variables will be written to this
vector, each element being one variable name. They will be sorted using
the <
operator of std::string
. (The amount
of found variables can be retrieved, rather obviously, with the
size()
method of the vector.)
useDegrees
: As with Parse()
.
As with Parse()
, the return value will be -1
if
the parsing succeeded, else an index to the location of the error. None of
the specified return values will be modified in case of error.
By default FunctionParser::Eval()
will perform certain sanity
checks before performing certain operations. For example, before calling the
sqrt
function, it will check if the parameter is negative, and
if so, it will set the proper error code instead of calling the function.
These checks include:
However, the library can not guarantee that it will catch all possible floating point errors before performing them, because this is impossible to do with standard C++. For example, dividing a very large value by a value which is very close to zero, or calculating the logarithm of a very small value may overflow the result, as well as multiplying two very large values. Raising a negative number to a non-integral power may cause a NaN result, etc.
In general, as stated, the library cannot guarantee that floating point errors will never happen during evaluation. This can make the library to return the floating point values inf and NaN. Moreover, if floating point errors cause an interrupt in the target computer architecture and/or when using certain compiler settings, this library cannot guarantee that it will never happen.
Since not all error situations can be caught, and since the sanity checks
only slow down the evaluation (although only very slightly), the precompiler
constant FP_NO_EVALUATION_CHECKS
can be used to turn all the
checks off. This might make the evaluation slightly faster in certain
situations.
Note that the optimizer never performs any sanity checks.
None of the member functions of the FunctionParser class are thread-safe.
Most prominently, the Eval()
function is not thread-safe.
(In other words, the Eval()
function of a single FunctionParser
instance cannot be safely called simultaneously by two threads.)
There are ways to use this library in a thread-safe way, though. If each
thread uses its own FunctionParser instance, no problems will obviously
happen. Note, however, that if these instances need to be a copy of a given
FunctionParser instance (eg. one where the user has entered a function),
a deep copy of this instance has to be performed for each thread. By
default FunctionParser uses shallow-copying (copy-on-write), which means
that a simple assignment of copy construction will not copy the data itself.
To force a deep copy you can all the ForceDeepCopy()
function on
each of the instances of each thread after the assignment or copying has been
done.
Another possibility is to compile the FunctionParser library so that
its Eval()
function will be thread-safe. (This can be done by
defining the FP_USE_THREAD_SAFE_EVAL
or the
FP_USE_THREAD_SAFE_EVAL_WITH_ALLOCA
precompiler constant.) As long as only one thread calls the other functions
of FunctionParser, the other threads can safely call the Eval()
of this one instance.
Note, however, that compiling the library like this can make
Eval()
slightly slower. (The alloca
version, if
supported by the compiler, will not be as slow.)
The function string understood by the class is very similar to the C-syntax. Arithmetic float expressions can be created from float literals, variables or functions using the following operators in this order of precedence:
() |
expressions in parentheses first |
A unit |
a unit multiplier (if one has been added) |
A^B |
exponentiation (A raised to the power B) |
-A |
unary minus |
!A |
unary logical not (result is 1 if int(A) is 0, else 0) |
A*B A/B A%B |
multiplication, division and modulo |
A+B A-B |
addition and subtraction |
A=B A<B A<=B |
comparison between A and B (result is either 0 or 1) |
A&B |
result is 1 if int(A) and int(B) differ from
0, else 0 |
A|B |
result is 1 if int(A) or int(B) differ from 0,
else 0 |
Since the unary minus has higher precedence than any other operator, for
example the following expression is valid: x*-y
The comparison operators use an epsilon value, so expressions which may
differ in very least-significant digits should work correctly. For example,
"0.1+0.1+0.1+0.1+0.1+0.1+0.1+0.1+0.1+0.1 = 1"
should always
return 1, and the same comparison done with ">
" or
"<
" should always return 0. (The epsilon value can be
configured in the fpconfig.hh
file.)
Without epsilon this comparison probably returns the wrong value.
The class supports these functions:
abs(A) |
Absolute value of A. If A is negative, returns -A otherwise returns A. |
acos(A) |
Arc-cosine of A. Returns the angle, measured in radians, whose cosine is A. |
acosh(A) |
Same as acos() but for hyperbolic cosine. |
asin(A) |
Arc-sine of A. Returns the angle, measured in radians, whose sine is A. |
asinh(A) |
Same as asin() but for hyperbolic sine. |
atan(A) |
Arc-tangent of (A). Returns the angle, measured in radians, whose tangent is (A). |
atan2(A,B) |
Arc-tangent of A/B. The two main differences to atan() is that it will return the right angle depending on the signs of A and B (atan() can only return values betwen -pi/2 and pi/2), and that the return value of pi/2 and -pi/2 are possible. |
atanh(A) |
Same as atan() but for hyperbolic tangent. |
ceil(A) |
Ceiling of A. Returns the smallest integer greater than A. Rounds up to the next higher integer. |
cos(A) |
Cosine of A. Returns the cosine of the angle A, where A is measured in radians. |
cosh(A) |
Same as cos() but for hyperbolic cosine. |
cot(A) |
Cotangent of A (equivalent to 1/tan(A)). |
csc(A) |
Cosecant of A (equivalent to 1/sin(A)). |
eval(...) |
This a recursive call to the function to be evaluated. The
number of parameters must be the same as the number of parameters
taken by the function. Must be called inside if() to avoid
infinite recursion. |
exp(A) |
Exponential of A. Returns the value of e raised to the power A where e is the base of the natural logarithm, i.e. the non-repeating value approximately equal to 2.71828182846. |
floor(A) |
Floor of A. Returns the largest integer less than A. Rounds down to the next lower integer. |
if(A,B,C) |
If int(A) differs from 0, the return value of this function is B,
else C. Only the parameter which needs to be evaluated is
evaluated, the other parameter is skipped; this makes it safe to
use eval() in them. |
int(A) |
Rounds A to the closest integer. 0.5 is rounded to 1. |
log(A) |
Natural (base e) logarithm of A. |
log10(A) |
Base 10 logarithm of A. |
max(A,B) |
If A>B, the result is A, else B. |
min(A,B) |
If A<B, the result is A, else B. |
pow(A,B) |
Exponentiation (A raised to the power B). |
sec(A) |
Secant of A (equivalent to 1/cos(A)). |
sin(A) |
Sine of A. Returns the sine of the angle A, where A is measured in radians. |
sinh(A) |
Same as sin() but for hyperbolic sine. |
sqrt(A) |
Square root of A. Returns the value whose square is A. |
tan(A) |
Tangent of A. Returns the tangent of the angle A, where A is measured in radians. |
tanh(A) |
Same as tan() but for hyperbolic tangent. |
Examples of function string understood by the class:
"1+2"
"x-1"
"-sin(sqrt(x^2+y^2))"
"sqrt(XCoord*XCoord + YCoord*YCoord)"
An example of a recursive function is the factorial function:
"if(n>1, n*eval(n-1), 1)"
Note that a recursive call has some overhead, which makes it a bit slower than any other operation. It may be a good idea to avoid recursive functions in very time-critical applications. Recursion also takes some memory, so extremely deep recursions should be avoided (eg. millions of nested recursive calls).
Also note that even though the maximum recursion level of
eval()
is limited, it is possible to write functions which
never reach that level but still take enormous amounts of time to evaluate.
This can sometimes be undesirable because it is prone to exploitation,
which is why eval()
is disabled by default. It can be enabled
in the fpconfig.hh
file.
Often the same constants (such as pi and e) and other
user-defined identifiers (such as units) are always used in all the
FunctionParser
objects throughout the program. It would be
troublesome to always have to manually add these constants every time a
new parser object is created.
There is, however, a simple way to always add these user-defined identifiers to all instances. Write a class like this:
class ParserWithConsts: public FunctionParser { public: ParserWithConsts() { AddConstant("pi", 3.14159265358979323846); AddConstant("e", 2.71828182845904523536); } };
Now instead of using FunctionParser
, always use
ParserWithConsts
. It will behave identically except that the
constants (and possibly other user-defined identifiers) will always be
automatically defined. (Objects of this type even survive
slicing, so
they are completely safe to use anywhere.)
Any comments, bug reports, etc. should be sent to warp@iki.fi
Copyright © 2003-2008 Juha Nieminen, Joel Yliluoma
This library is distributed under two distinct usage licenses depending on the software ("Software" below) which uses the Function Parser library ("Library" below).
The reason for having two distinct usage licenses is to make the library compatible with the GPL license while still being usable in other non-GPL (even commercial) software.
If the Software using the Library is distributed under the GPL license, then the Library can be used under the GPL license as well.
The Library will be under the GPL license only when used with the Software. If the Library is separated from the Software and used in another different software under a different license, then the Library will have the B) license below.
Exception to the above: If the Library is modified for the GPL Software, then the Library cannot be used with the B) license without the express permission of the author of the modifications. A modified library will be under the GPL license by default. That is, only the original, unmodified version of the Library can be taken to another software with the B) license below.
The author of the Software should provide an URL to the original
version of the Library if the one used in the Software has been
modified. (http://iki.fi/warp/FunctionParser/
)
This text file must be distributed in its original intact form along with the sources of the Library. (Documentation about possible modifications to the library should be put in a different text file.)
As per the GPL license, the copyright notification at the beginning of this section should accompany any significant portions of the Library. Proper credits in any Software using the Library is appreciated.
If the Software using the Library is not distributed under the GPL license but under any other license, then the following usage license applies to the Library:
If you are making a free program or a shareware program with just a nominal price (5 US dollars or less), you don't have to ask for permission.
In any case, I DON'T WANT MONEY for the usage of this library. It is free, period.
If you DO include the source code for this library, this text file must be included in its original intact form.
Also a URL to the library download page would be nice, although not required. The official URL is:
http://iki.fi/warp/FunctionParser/
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
The software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.
Explanation of the section 2 of the B) license above:
The section 2 tries to define "fair use" of the library in commercial programs.
"Fair use" of the library means that the program is not heavily dependent on the library, but the library only provides a minor secondary feature to the program.
"Heavily dependent" means that the program depends so much on the library that without it the functionality of the program would be seriously degraded or the program would even become completely non-functional.
In other words: If the program does not depend heavily on the library, that is, the library only provides a minor secondary feature which could be removed without the program being degraded in any considerable way, then it's OK to use the library in the commercial program.
If, however, the program depends so heavily on the library that removing it would make the program non-functional or degrade its functionality considerably, then it's NOT OK to use the library.
The ideology behind this is that it's not fair to use a free library as a base for a commercial program, but it's fair if the library is just a minor, unimportant extra.
If you are going to ask me for permission to use the library in a commercial program, please describe the feature which the library will be providing and how important it is to the program.