Function Parser for C++ v4.5.2 : Documentation

# Function Parser for C++ v4.5.2

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.

## Table of contents:

- What's new
- Preface
- Usage
  - Parser types
  - Configuring the compilation
  - Copying and assignment
  - Short descriptions of FunctionParser methods
  - Long descriptions of FunctionParser methods
    - `Parse()`
    - `setDelimiterChar()`
    - `ErrorMsg()`
    - `GetParseErrorType()`
    - `Eval()`
    - `EvalError()`
    - `Optimize()`
    - `AddConstant()`
    - `AddUnit()`
    - `AddFunction()` (C++ function)
    - `AddFunction()` (FunctionParser)
    - `AddFunctionWrapper()`
    - `RemoveIdentifier()`
    - `ParseAndDeduceVariables()`
  - Specialized function objects
  - FunctionParserBase
- Syntax
  - Numeric literals
  - Identifier names
  - The function string syntax
  - Inline variables
  - Whitespace
- Miscellaneous
  - About floating point accuracy
  - About evaluation-time checks
  - About thread safety
  - Tips and tricks
  - Contacting the author
- Usage license

## What's new

What's new in v4.5.2

- Fixed several optimizer bugs.
- Fixed compilation problems with Visual Studio 2013 and gcc.

## Preface

This C++ library offers a class which can be used to parse and evaluate a mathematical function from a string (which might be eg. requested from the user). The syntax of the function string is similar to mathematical expressions written in C/C++ (the exact syntax is specified later in this document). The function can then be evaluated with different values of variables.

For example, a function like "`sin(sqrt(x*x+y*y))`" can be parsed from a string (either `std::string` or a C-style string) and then evaluated with different values of `x` and `y`. This library can be useful for evaluating user-inputted functions, or in some cases interpreting mathematical expressions in a scripting language.

This library aims for maximum speed in both parsing and evaluation, while keeping maximum portability. The library should compile and work with any standard-conforming C++ compiler.

Different numerical types are supported: `double`, `float`, `long double`, `long int`, `std::complex` (of types `double`, `float` and `long double`), multiple-precision floating point numbers using the MPFR library, and arbitrary precision integers using the GMP library. (Note that it's not necessary for these two libraries to exist in the system in order to use the Function Parser library with the other numerical types. Support for these libraries is optionally compiled in using preprocessor settings.)

## Usage

To use the `FunctionParser` class, you have to include `"fparser.hh"` in your source code files which use the `FunctionParser` class.

If you are going to use the MPFR version of the library, you need to include `"fparser_mpfr.hh"`. If you are going to use the GMP version of the library, you need to include `"fparser_gmpint.hh"`. (Note that support for these special parser versions needs to be specified with preprocessor macros. See the documentation below for details.)

When compiling, you have to compile `fparser.cc` and `fpoptimizer.cc` and link them to the main program. In many 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 going to use the MPFR or the GMP versions of the library, you also need to add `mpfr/MpfrFloat.cc` or `mpfr/GmpInt.cc` files to your project, respectively. Otherwise they should not be added to the project.

Note that part of the library source code is inside several `.inc` files inside the `extrasrc` subdirectory (these files contain auto-generated C++ code), provided in the library package. These files are used by `fparser.cc` and don't need to be added explicitly to the project in most IDEs (such as Visual Studio). Basically, you don't need to do anything with these files, other than keep them in the `extrasrc` subdirectory.

Simple usage example of the library:

        FunctionParser fp;
        fp.Parse("sqrt(x*x + y*y)", "x,y");
        double variables[2] = { 1.5, 2.9 };
        double result = fp.Eval(variables);

### Parser types

Different versions of the function parser class are supported, using different floating point or integral types for function evaluation.

All the classes other than the default one, `FunctionParser`, need to be enabled at compile time by defining a preprocessor macro (specified below) either in the `fpconfig.hh` file or your compiler settings. (The reason for this is that every parser that is included in the compilation process will make the compilation slower and increase the size of the executable, so they are compiled only on demand. Also, the GMP and MPFR versions of the parser require for those libraries to be available, which is often not the case.)

Note that if you try to use the other class types without enabling them with the correspondent preprocessor macro, you will get a linker error (rather than a compiler error) because those classes will not have been instantiated when the library was compiled.

Currently the `Optimize()` method works only for the `FunctionParser`, `FunctionParser_f` and `FunctionParser_ld` classes. For the other types it can be called but it does nothing.

`FunctionParser`

  This is the default class, which uses `double` as its numerical type. This is the only class enabled by default.

  If you use some other type than this one, and you don't want this version of the class compiled into the library, you can define the preprocessor macro `FP_DISABLE_DOUBLE_TYPE`.

`FunctionParser_f`

  This parser uses `float` as its numerical type.

  The `FP_SUPPORT_FLOAT_TYPE` preprocessor macro needs to be defined for this class to be enabled.

`FunctionParser_ld`

  This parser uses `long double` as its numerical type.

  The `FP_SUPPORT_LONG_DOUBLE_TYPE` preprocessor macro needs to be defined for this class to be enabled.

  Note that the `FP_USE_STRTOLD` preprocessor macro should also be defined when using this version of the parser if the compiler supports the (C99) function `strtold()`. (See documentation below.)

`FunctionParser_li`

  This parser uses `long int` as its numerical type.

  The `FP_SUPPORT_LONG_INT_TYPE` preprocessor macro needs to be defined for this class to be enabled.

  Note that this version of the class uses a reduced function syntax with support only for functions which are feasible to be used with integral types (namely `abs()`, `eval()`, `if()`, `min()` and `max()`, besides basic arithmetic operators, except for the power operator).

`FunctionParser_cd`, `FunctionParser_cf`, `FunctionParser_cld`

  These parsers use `std::complex<double>`, `std::complex<float>` and `std::complex<long double>` as their numerical type, respectively.

  The preprocessor macros to enable them are `FP_SUPPORT_COMPLEX_DOUBLE_TYPE`, `FP_SUPPORT_COMPLEX_FLOAT_TYPE` and `FP_SUPPORT_COMPLEX_LONG_DOUBLE_TYPE`.

  If `FunctionParser_cld` is used, the `FP_USE_STRTOLD` macro should also be defined if the compiler supports the `strtold()` function.

`FunctionParser_mpfr`

  This parser uses `MpfrFloat` as its numerical type.

  The `FP_SUPPORT_MPFR_FLOAT_TYPE` preprocessor macro needs to be defined for this class to be enabled.

  Note that to use this version of the parser, `"fparser_mpfr.hh"` needs to be included.

  `MpfrFloat` is an auxiliary class which uses the MPFR library for multiple-precision floating point numbers. The class behaves largely like a floating point type, and is declared in the `mpfr/MpfrFloat.hh` file (see that file for info about the public interface of the class).

  If this class is enabled, `mpfr/MpfrFloat.cc` needs to be compiled into the project, as well as the GMP and MPFR libraries. (With the gcc compiler this means using the linker options "`-lgmp -lmpfr`".)

`FunctionParser_gmpint`

  This parser uses `GmpInt` as its numerical type.

  The `FP_SUPPORT_GMP_INT_TYPE` preprocessor macro needs to be defined for this class to be enabled.

  Note that to use this version of the parser, `"fparser_gmpint.hh"` needs to be included.

  `GmpInt` is an auxiliary class which uses the GMP library for arbitrary-precision integer numbers. The class behaves largely like an integer type, and is declared in the `mpfr/GmpInt.hh` file (see that file for info about the public interface of the class).

  If this class is enabled, `mpfr/GmpInt.cc` needs to be compiled into the project, as well as the GMP library.

  This version of the class also uses a reduced version of the syntax, like the `long int` version.

  Note: Since there's no upper limit to the size of GMP integers, this version of the class should be used with care in situations where malicious users might be able to exploit it to make the program run out of memory. An example of this would be a server-side application usable through the WWW.

Note that these different classes are completely independent and instances of different classes cannot be given to each other using the `AddFunction()` method. Only objects of the same type can be given to that method.

The rest of the documentation assumes that `FunctionParser` (which uses the `double` type) is used. The usage of the other classes is identical except that `double` is replaced with the correspondent type used by that class. (In other words, whenever the rest of this documentation uses the type keyword '`double`', the correspondent type should be used instead, when using another version of the class.)

### Configuring the compilation

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_USE_STRTOLD` : (Default off)

  If `FunctionParser_ld` or `FunctionParser_cld` are used, this preprocessor macro should be defined if the compiler supports the (C99) function `strtold()`. If not, then numeric literals will be parsed with double precision only, which in most systems is less accurate than long double precision, which will cause small rounding errors. (This setting has no effect on the other parser types.) Note that `strtold()` will also be automatically used if `__cplusplus` indicates that C++11 is in use.

`FP_SUPPORT_CPLUSPLUS11_MATH_FUNCS` : (Default off)

  Use C++11 math functions where applicable. (These are ostensibly faster than the equivalent formulas using C++98 math functions.) Note that not all compilers support these functions (even if they otherwise support C++11.)

`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_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.

  Also note that the MPFR and GMP versions of the library cannot be made thread-safe, and thus this setting has no effect on them.

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

### Copying and assignment

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.

### Short descriptions of FunctionParser methods

    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.)

    static double epsilon();
    static void setEpsilon(double);

Setter and getter for the epsilon value used with comparison operators.

    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.

### Long descriptions of FunctionParser methods

    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:

- On success the function returns `-1`.
- On error the function returns an index to where the error was found (`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).

    static double epsilon();
    static void setEpsilon(double);

Comparison operators (for the non-integral versions of the parser) use an epsilon value to account for floating point calculation rounding errors. This epsilon value can be set and read with these functions. (Note that the specified value will be used by all instances of FunctionParser.) If not specified, the default values are:

- double: 1e-12
- float: 1e-5
- long double: 1e-14
- MpfrFloat: The value of MpfrFloat::someEpsilon()

    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"
`UNKNOWN_IDENTIFIER` | "Syntax error: Unknown identifier"
`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:

- On success returns the evaluated value of the function given to `Parse()`.
- On error (such as division by 0) the return value is unspecified, probably 0.

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:

- 1: division by zero
- 2: sqrt error (sqrt of a negative value)
- 3: log error (logarithm of a negative value)
- 4: trigonometric error (asin or acos of illegal value)
- 5: maximum recursion level in `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:

- The name of the function. The name follows the same naming conventions as variable names.
- A C++ function, which will be called when evaluating the function string (if the user-given function is called there). The C++ function must have the form:

  `double functionName(const double* params);`

- The number of parameters the function takes. 0 is a valid value in which case the function takes no parameters (such function should simply ignore the `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:

- The FunctionParser instance given as parameter must be initialized with a `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)`.
- The amount of variables in the FunctionParser instance given as parameter must not change after it has been given to the `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.
- The FunctionParser instance given as parameter will not be copied internally, only referenced. Thus the FunctionParser instance given as parameter must exist for as long as the other FunctionParser instance uses it.

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).

    template<typename DerivedWrapper>
    bool AddFunctionWrapper(const std::string& name, const DerivedWrapper&,
                            unsigned paramsAmount);

See section on specialized function objects.

    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.

### Specialized function objects

The `AddFunction()` method can be used to add a new user-defined function to the parser, its implementation being called through a C++ function pointer. Sometimes this might not be enough, though. For example, one might want to use `boost::function` or other similar specialized stateful function objects instead of raw function pointers. This library provides a mechanism to achieve this.

#### Creating and adding a specialized function object

In order to create a specialized function object, create a class derived from the `FunctionParser::FunctionWrapper` class. This class declares a virtual function named `callFunction` that the derived class must implement. For example:

    class MyFunctionWrapper:
        public FunctionParser::FunctionWrapper
    {
     public:
        virtual double callFunction(const double* values)
        {
            // Perform the actual function call here, like:
            return someFunctionSomewhere(values);

            // In principle the result could also be
            // calculated here, like for example:
            return values[0] * values[0];
        }
    };

You can then add an instance of this class to `FunctionParser` using the `AddFunctionWrapper()` method, which works like `AddFunction()`, but takes a wrapper object instead of a function pointer as parameter. For example:

    MyFunctionWrapper wrapper;
    parser.AddFunctionWrapper("funcName", wrapper, 1);

Note that `FunctionParser` will internally create a copy of the wrapper object, managing the lifetime of this copy, and thus the object given as parameter does not need to exist for as long as the `FunctionParser` instance. Hence the above could also be written as:

    parser.AddFunctionWrapper("funcName", MyFunctionWrapper(), 1);

Note that this also means that the wrapper class must have a working copy constructor.

Also note that if the `FunctionParser` instance is copied, all the copies will share the same function wrapper objects given to the original.

#### Retrieving specialized function objects

As noted, the library will internally make a copy of the wrapper object, and thus it will be separate from the one which was given as parameter to `AddFunctionWrapper()`. In some cases it may be necessary to retrieve this wrapper object (for example to read or change its state). This can be done with the `GetFunctionWrapper()` method, which takes the name of the function and returns a pointer to the wrapper object, or null if no such object exists with that name.

Note that the returned pointer will be of type `FunctionParser::FunctionWrapper`. In order to get a pointer to the actual derived type, the calling code should perform a `dynamic_cast`, for example like this:

    MyFunctionWrapper* wrapper =
        dynamic_cast<MyFunctionWrapper*>
        (parser.GetFunctionWrapper("funcName"));

    if(!wrapper) { /* oops, the retrieval failed */ }
    else ...

(Using dynamic cast rather than a static cast adds safety because if you accidentally try to downcast to the wrong type, the pointer will become null.)

The calling code is free to modify the object in any way it wants, but it must not delete it (because `FunctionParser` itself handles this).

### FunctionParserBase

All the different parser types are derived from a templated base class named `FunctionParserBase`. In normal use it's not necessary to directly refer to this base class in the calling code. However, if the calling code also needs to be templated (with respect to the numerical type), then using `FunctionParserBase` directly is the easiest way to achieve this.

For example, if you want to make a function that handles more than one type of parser, it can be done like this:

    template<typename Value_t>
    void someFunction(FunctionParserBase<Value_t>& parser)
    {
        // do something with 'parser' here
    }

Now it's convenient to call that function with more than one type of parser, for example:

    FunctionParser realParser;
    FunctionParser_cd complexParser;

    someFunction(realParser);
    someFunction(complexParser);

Another example is a class that inherits from `FunctionParser` which also wants to support different numerical types. Such class can be declared as:

    template<typename Value_t>
    class SpecializedParser: public FunctionParserBase<Value_t>
    {
        ...
    };

## Syntax

### Numeric literals

A numeric literal is a fixed numerical value in the input function string (either a floating point value or an integer value, depending on the parser type).

An integer literal can consist solely of numerical digits (possibly with a preceding unary minus). For example, "`12345`".

If the literal is preceded by the characters "`0x`", it will be interpreted as a hexadecimal literal, where digits can also include the letters from '`A`' to '`F`' (in either uppercase or lowercase). For example, "`0x89ABC`" (which corresponds to the value 563900).

A floating point literal (only supported by the floating point type parsers) may additionally include a decimal point followed by the decimal part of the value, such as for example "`12.34`", optionally followed by a decimal exponent.

A decimal exponent consists of an '`E`' or '`e`', followed by an optional plus or minus sign, followed by decimal digits, and indicates multiplication by a power of 10. For example, "`1.2e5`" (which is equivalent to the value 120000).

If a floating point literal is preceded by the characters "`0x`" it will be interpreted in hexadecimal. A hexadecimal floating point literal consists of a hexadecimal value, with an optional decimal point, followed optionally by a binary exponent in base 10 (in other words, the exponent is not in hexadecimal).

A binary exponent has the same format as a decimal exponent, except that '`P`' or '`p`' is used. A binary exponent indicates multiplication by a power of 2. For example, "`0xA.Bp10`" (which is equivalent to the value 10944).

With the complex versions of the library, the imaginary part of a numeric literal is written as a regular numeric literal with an '`i`' appended, for example "`5i`". Note that when also specifying the real part of a complex literal, parentheses should be used to avoid precedence problems. (For example, "`(2+5i) * x`" is not the same thing as "`2+5i * x`". The latter would be equivalent to "`2 + (5i * x)`".)

### Identifier names

An identifier is the name of a function (internal or user-defined), variable, constant or unit. New identifiers can be specified with the functions described in the earlier subsections in this document.

The name of an identifier can use any alphanumeric characters, the underscore character and any UTF8-encoded unicode character, excluding those denoting whitespace. 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.

### The function string syntax

The function string understood by the class is very similar (but not completely identical in all aspects) to mathematical expressions in the C/C++ languages. 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 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. Note: Regardless of the values, both operands are always evaluated. However, if the expression is optimized, it may be changed such that only one of the operands is evaluated, according to standard shortcut logical operation semantics.
`A|B` | result is 1 if `int(A)` or `int(B)` differ from 0, else 0. Note: Regardless of the values, both operands are always evaluated. However, if the expression is optimized, it may be changed such that only one of the operands is evaluated, according to standard shortcut logical operation semantics.

(Note that currently the exponentiation operator is not supported for `FunctionParser_li` nor `FunctionParser_gmpint`. With the former the result would very easily overflow, making its usefulness questionable. With the latter it could be easily abused to make the program run out of memory; think of a function like "10^10^10^100000".)

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 (magnitude) of A. With real numbers, if A is negative, returns -A otherwise returns A. With complex numbers, equivalent to `hypot(real(x),imag(x))`.
`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.
`arg(A)` | Phase angle of complex number A. Equivalent to `atan2(imag(x),real(x))`.
`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)` | Principal arc-tangent of A/B, using the signs of the two arguments to determine the quadrant of the result. Returns the solution to the two expressions hypot(A,B)*sin(x)=A, hypot(A,B)*cos(x)=B. The return value is in range -pi to pi, inclusive.
`atanh(A)` | Same as atan() but for hyperbolic tangent.
`cbrt(A)` | Cube root of A. Returns a solution to expression pow(x,3)=A.
`conj(A)` | Complex conjugate of A. Equivalent to `real(x) - 1i*imag(x)` or `polar(abs(x),-arg(x))`.
`ceil(A)` | Ceiling of A. Returns the smallest integer not smaller than A. Rounds up to the next higher integer. E.g. -2.9, -2.5 and -2.1 are rounded to -2.0, and 2.9, 2.5 and 2.1 are rounded to 3.0.
`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.
`exp2(A)` | Base 2 exponential of A. Equivalent to `pow(2,A)`.
`floor(A)` | Floor of A. Returns the largest integer not greater than A. Rounds down to the next lower integer. E.g. -2.9, -2.5 and -2.1 are rounded to -3.0, and 2.9, 2.5 and 2.1 are rounded to 2.0.
`hypot(A,B)` | Euclidean distance function. Equivalent to `sqrt(A^2+B^2)`.
`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.
`imag(A)` | Return the imaginary part of complex number A. Equivalent to `abs(A)*sin(arg(A))`.
`int(A)` | Rounds A to the closest integer. Equidistant values are rounded away from zero. E.g. -2.9 and -2.5 are rounded to -3.0; -2.1 is rounded to -2.0, and 2.9 and 2.5 are rounded to 3.0; 2.1 is rounded to 2.0.
`log(A)` | Natural (base e) logarithm of A. Returns the solution to expression exp(x)=A.
`log2(A)` | Base 2 logarithm of A. Equivalent to `log(A)/log(2)`.
`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.
`polar(A,B)` | Returns a complex number from magnitude A, phase angle B (in radians). Equivalent to `real(A)*(cos(real(B))+1i*sin(real(B)))`.
`pow(A,B)` | Exponentiation (A raised to the power B).
`real(A)` | Return the real part of complex number A. Equivalent to `abs(A)*cos(arg(A))`.
`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 a solution to expression pow(x,2)=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.
`trunc(A)` | Truncated value of A. Returns an integer corresponding to the value of A without its fractional part. E.g. -2.9, -2.5 and -2.1 are rounded to -2.0, and 2.9, 2.5 and 2.1 are rounded to 2.0.

(Note that for `FunctionParser_li` and `FunctionParser_gmpint` only the functions `abs()`, `eval()`, `if()`, `min()` and `max()` are supported.)

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.

### Inline variables

The function syntax supports defining new variables inside the function string itself. This can be done with the following syntax:

`"<variable name> := <expression>; <function>"`

For example:

`"length := sqrt(x*x+y*y); 2*length*sin(length)"`

(Spaces around the '`:=`' operator are optional.)

The obvious benefit of this is that if a long expression needs to be used in the function several times, this allows writing it only once and using a named variable from that point forward.

The variable name must be an unused identifier (in other words, not an existing function, variable or unit name).

The `<function>` part can have further inline variable definitions, and thus it's possible to have any amount of them, for example:

`"A := x^2; B := y^2; C := z^2; sqrt(A+B+C)"`

The expressions in subsequent inline variable definitions can use any of the previous inline variables. It is also possible to redefine an inline variable. For example:

`"A := x^2; A := 2*A; sqrt(A)"`

### Whitespace

Arbitrary amounts of whitespace can optionally be included between elements in the function string. The following unicode characters are interpreted as whitespace:

Character number | Character name | UTF-8 byte sequence
--- | --- | ---
U+0009 | HORIZONTAL TABULATION | 09
U+000A | LINE FEED | 0A
U+000B | VERTICAL TABULATION | 0B
U+000D | CARRIAGE RETURN | 0D
U+0020 | SPACE | 20
U+00A0 | NO-BREAK SPACE | C2 A0
U+2000 | EN QUAD | E2 80 80
U+2001 | EM QUAD | E2 80 81
U+2002 | EN SPACE | E2 80 82
U+2003 | EM SPACE | E2 80 83
U+2004 | THREE-PER-EM SPACE | E2 80 84
U+2005 | FOUR-PER-EM SPACE | E2 80 85
U+2006 | SIX-PER-EM SPACE | E2 80 86
U+2007 | FIGURE SPACE | E2 80 87
U+2008 | PUNCTUATION SPACE | E2 80 88
U+2009 | THIN SPACE | E2 80 89
U+200A | HAIR SPACE | E2 80 8A
U+200B | ZERO WIDTH SPACE | E2 80 8B
U+202F | NARROW NO-BREAK SPACE | E2 80 AF
U+205F | MEDIUM MATHEMATICAL SPACE | E2 81 9F
U+3000 | IDEOGRAPHIC SPACE | E3 80 80

## Miscellaneous

### About floating point accuracy

Note that if you are using `FunctionParser_ld` or `FunctionParser_cld` and you want calculations to be as accurate as the `long double` type allows, you should pay special attention to floating point literals in your own code. For example, this is a very typical mistake:

    FunctionParser_ld parser;
    parser.AddConstant("pi", 3.14159265358979323846);

The mistake might not be immediately apparent. The mistake is that a literal of type `double` is passed to the `AddConstant()` function even though it expects a value of type `long double`. In most systems the latter has more bits of precision than the former, which means that the value will have its least-significant bits clipped, introducing a rounding error. The proper way of making the above calls is:

    FunctionParser_ld parser;
    parser.AddConstant("pi", 3.14159265358979323846L);

The same principle should be used everywhere in your own code, if you are using the `long double` type.

This is especially important if you are using the `MpfrFloat` type (in which case its string-parsing constructor or its `ParseValue()` or `parseString()` member functions should be used instead of using numerical literals).

### About evaluation-time checks

`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:

- Division by (the exact value of) zero.
- Square root of a negative value.
- Logarithm of a non-positive value.
- Arcsine or arccosine of a value not in the range [-1, 1]. (This includes hyperbolic versions of the functions.)

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.

As a rule of thumb, the library will (by default) detect invalid operations if they are invalid for a range of values. For example, square root is undefined for all negative values, and arc sine is undefined only values outside the range [-1, 1]. In general, operations which are invalid for only one single value (rather than a contiguous range of values) will not be detected (division by the exact value of zero is an exception to this rule) nor will overflow/underflow situations.

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.

Note that the optimizer never performs any sanity checks.

### About thread safety

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.)

Also note that the MPFR and GMP versions of the library cannot be made thread-safe, and thus this setting has no effect on them.

### Tips and tricks

#### Add constants automatically to all parser objects

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.)

### Contacting the author

Any comments, bug reports, etc. should be sent to warp@iki.fi

## Usage license

Copyright © 2003-2011 Juha Nieminen, Joel Yliluoma

This Library is distributed under the Lesser General Public License (LGPL) version 3.