CalculatorTable of ContentsDerived Class
Math Parser for C++ Documentation

Documentation of Math Parser for C++ Library

Math Parser for C++ source code contains comments designed to make the source code self documenting.

Here is Math Parser for C++ Documentation generated by Doxygen.

Below is the summary of public interface of CMathParser class along with comments about each function.

#ifndef __MATH_PARSER_H_
#define __MATH_PARSER_H_

#include <map>
#include <vector>
#include <string>
#include <float.h>
#include <time.h>
#include <wchar.h>
#include <sstream>
#include <math.h>

using namespace std;

/**
 * CParserException is used to report errors during parsing and evaluation in
 * CMathParser class.
 * GetMessage() function can be used to retrieve error message.
 * GetInvalidPortionOfExpression() function reports the problematic
 * part of the mathematical expression that caused the error.
 */

template<typename _CharT> class CParserException {
public:
        //get error message:
        basic_string<_CharT> GetMessage() {
                return this->m_Message;
        }
        //get sub expression that we could not parse (might be empty):
        basic_string<_CharT> GetInvalidPortionOfExpression() {
                return this->m_InvalidPortionOfExpression;
        }
};

/**
 * CMathParser template class implements mathematical expression parsing algorithm.
 * User can define variables, functions, set variable values,
 * set a mathematical expression and request that it's value be computed.
 * CMathParser will convert the string expression to an internal representation of a tree
 * structure. If Optimization is turned on, it will walk the tree to convert non-parametric
 * branches (branches whose value do not depend on variables) into a constant value.
 * Once this is done successfully, the expression can be evaluated very quickly for
 * different variable values.
 */

template<typename _CharT, typename _ValueT> class CMathParser {
        friend class COneParamNode<_CharT, _ValueT>;
        friend class CTwoParamNode<_CharT, _ValueT>;
        friend class CNParamNode<_CharT, _ValueT>;

public:
        /**
         * String type used in variable, function names, and reporting messages.
         * It is nothing but a basic_string<> of std.
         */

        typedef basic_string<_CharT> string_t;

        /**
         * ParserFunction type specifies the prototype of the functions that users can
         * add to the list of available functions with N parameters to be used in an expression.
         * p[] array holds the value for each paramater.
         * count is the number of paramaters (number of elements in p[]).
         * pParentParser parameter is a way to carry the current context into the user defined function.
         * Applications can create their own parsers that are "Application Aware". Then inside the user
         * defined function, pParentParser can be cast to application specific parser type and it's members
         * can be used to access application domain.
         */

        typedef _ValueT ParserFunction(CMathParser<typename _CharT, typename _ValueT> pParentParser,
                        const _ValueT p[], const int count);

        typedef ParserFunction* PParserFunction;

        typedef CParserException<_CharT> ParserException;

public:
        /**
         * Constructor to create a CMathParser instance.
         * It initializes member variables and creates default functions and variables.
         */

        CMathParser();
        /**
         * Virtual destructor to free memory.
         */

        virtual ~CMathParser();

        /**
         * Parse the expression. It is fast to parse the expression once,
         * then loop to evaluate the expression multiple times by setting different variable
         * values.
         * throws CMathParser::ParserException on error.
         */

        void Parse() throw (ParserException);

        /**
         * Returns TRUE if the given function name is already registered as a function.
         */

        BOOL IsFunction(string_t funcName);

        /**
         * Returns TRUE if the given variable name is already registered as a variable.
         */

        BOOL IsVariable(string_t varName);

        /**
         * Return TRUE if a given variable was used in the current expression.
         * Return FALSE if the expression does not contain this variable.
         * Throw CMathParser::ParserException if the expression cannot be parsed.
         */

        BOOL IsVariableUsed(string_t varName) throw (ParserException);
       
        /**
         * Return TRUE if a given function is being used in the current expression.
         * Return FALSE if the expression is not using the function.
         * Throw CMathParser::ParserException if the expression cannot be parsed.
         */

        BOOL IsFuncUsed(string_t funcName) throw (ParserException);

        /**
         * Free the parse tree that was used to parse previous expression.
         * This does not have to be called explicitly.
         * This is only useful for an unusual case where a very big expression was
         * parsed and tree takes alot of memory and you want to free it because
         * you will not use the parser instance for a while.
         * Otherwise, next expression parse will delete previous tree.
         */

        void FreeParseTree();
       
        /**
         * Init random _ValueT generator for rnd built-in function.
         */

        void Randomize();
       
        /**
         * Delete all functions defined for the parser.
         */

        void DeleteAllFuncs();
       
        /**
         * Delete all defined variables.
         */

        void DeleteAllVars();

        /**
         * Delete a function from defined functions list.
         * Ignore if not found.
         */

        void DeleteFunc(string_t funcName);

        /**
         * Delete an existing variable name.
         * If it does not exist, it is ignored.
         */

        void DeleteVar(string_t varName);
       
        /**
         * Define a variable with initial value.
         */

        void CreateVar(string_t varName, _ValueT varValue);

 

        /**
         * Create a user defined function with given name, number of params, function address to call.
         * The uppercase version of given function name can be used in the expressions.
         * If the expression does not specify correct number of parameters, then a
         * CMathParser::ParserException will be thrown during parsing. if number of parameters is specified as -1, then the
         * function can take 1 or more number of parameters. Number of parameters will not be verified
         * during parse operation.
         * If invalid number of parameters are passed to a function, the function implementation itself can choose
         * to throw exception during evaluate operation.
         */

        void CreateFunc(string_t newFuncName, int numParams,
                        PParserFunction funcAddress) throw(ParserException);
        /**
         * Create default built-in variables such as X, Y, PI.
         * Override to define different set of variables.
         */

        virtual void CreateDefaultVars();

        /**
         * Create default functions.
         * You can override CreateDefaultFuncs to define (or not define)
         * a different set of functions.
         *
         * Predefined functions that take one parameter are:
                *        SQR: Square function which can be used as SQR(X)
                *
                *        SIN: Sinus function which can be used as SIN(X), X is a real-type expression. Sin returns the sine of the angle X in radians.
                *
                *        COS: Cosinus function which can be used as COS(X), X is a real-type expression. COS returns the cosine of the angle X in radians.
                *
                *        ATAN: ArcTangent function which can be used as ATAN(X)
                *
                *        SINH: Sinus Hyperbolic function which can be used as SINH(X)
                *
                *        COSH: Cosinus Hyperbolic function which can be used as COSH(X)
                *
                *        COTAN: which can be used as COTAN(X)
                *
                *        TAN: which can be used as TAN(X)
                *
                *        EXP: which can be used as EXP(X)
                *
                *        LN: natural log, which can be used as LN(X)
                *
                *        LOG: 10 based log, which can be used as LOG(X)
                *
                *        SQRT: which can be used as SQRT(X)
                *
                *        ABS: absolute value, which can be used as ABS(X)
                *
                *        SIGN: SIGN(X) returns -1 if X<0; +1 if X>0, 0 if X=0; it can be used as SQR(X)
                *
                *        TRUNC: Discards the fractional part of a number. e.g. TRUNC(-3.2) is -3, TRUNC(3.2) is 3.
                *
                *        CEIL: CEIL(-3.2) = -3, CEIL(3.2) = 4
                *
                *        FLOOR: FLOOR(-3.2) = -4, FLOOR(3.2) = 3
                *
                *        RND:  Random number generator.
                *
                *        RND(X) generates a random INTEGER number such that 0 <= Result < int(X). Call Parser.Randomize to initialize the random number generator with a random seed value before using RND function in your expression.
                *
                *        RANDOM: Random number generator.
                *
                *        RANDOM(X) generates a random floating point number such that 0 <= Result < X. Call Parser.Randomize to initialize the random number generator with a random seed value before using RANDOM function in your expression.
                *
                *        Predefined functions that take two parameters are:
                *
                *        INTPOW: The INTPOW function raises Base to an integral power. INTPOW(2, 3) = 8. Note that result of INTPOW(2, 3.4) = 8 as well.
                *
                *        POW: The Power function raises Base to any power. For fractional exponents or exponents greater than MaxInt, Base must be greater than 0.
                *
                *        LOGN: The LogN function returns the log base N of X. Example: LOGN(10, 100) = 2
                *
                *        MIN: MIN(2, 3, 4, 5) is 2.
                *
                *        MAX: MAX(2, 3, 1, 0) is 3.
                *
                *        IF: IF(1, 2, 3) is 2.
                *
                *        SUM: SUM(1, 2, 3, 4) is 10.
                *
                *        AVG: AVG(1, 2, 3, 4, 5) is 3.
         *
         */

        virtual void CreateDefaultFuncs();
       
        /**
         * Evaluate the expression to it's value.
         * Throw CMathParser::ParserException if the expression can not be parsed.
         */

        _ValueT Evaluate() throw (ParserException);

        /**
         * Return current optimization setting.
         * If OptimizationOn is set to TRUE, then the parser will eliminate
         * expression sub-trees that evaluate to a constant expression so that
         * they can be skipped in repeated evaluations.
         */

        BOOL GetOptimizationOn();

        /**
         * If OptimizationOn is set to TRUE, then the parser will eliminate
         * expression sub-trees that evaluate to a constant expression so that
         * they can be skipped in repeated evaluations.
         */

        void SetOptimizationOn(BOOL newVal);

        /**
         * Set the value of a variable. This will define the variable if it is not defined yet.
         */

        void SetVariable(string_t varName, _ValueT varValue) throw(ParserException);
       
        /**
         * Get the current value of a variable.
         * Throws CMathParser::ParserException if variable is not defined yet.
         */

        _ValueT GetVariable(string_t varName);

        /**
         * Return value of variable Y.
         *
         * Since X, and Y are commonly used in math expressions, CMathParser defines them by default.
         * If you don't like X and Y, you can override CreateDefaultVars, or you can
         * call DeleteAllVars() function.
         */

        _ValueT GetY();
       
        /**
         * Set value of variable Y.
         *
         * Since X, and Y are commonly used in math expressions, CMathParser defines them by default.
         * If you don't like X and Y, you can override CreateDefaultVars, or you can
         * call DeleteAllVars() function.
         */

        void SetY(_ValueT newVal);
       
        /**
         * Return value of variable X.
         *
         * Since X, and Y are commonly used in math expressions, CMathParser defines them by default.
         * If you don't like X and Y, you can override CreateDefaultVars, or you can
         * call DeleteAllVars() function.
         */

        _ValueT GetX();
       
        /**
         * Set value of variable X.
         *
         * Since X, and Y are commonly used in math expressions, CMathParser defines them by default.
         * If you don't like X and Y, you can override CreateDefaultVars, or you can
         * call DeleteAllVars() function.
         */

        void SetX(_ValueT newVal);
       
        /**
         * Parse the expression, evaluate it and return the result.
         */

        _ValueT GetValue();

        /**
         * Set the expression to parse.
         * The expression may contain :
         * 1. variables such as X, Y, Z, TEMP, STRESS, STRAIN etc.
         * 2. functions such as SIN(X), MIN(A,B), MYFUNC(D)
         * 3. constants such as 2, 3, 50
         * 4. scientific notation like: 3E+10
         * 5. aithmetic operators: +,-,*,/,%(modulus),^(power)
         * 6. logical operators  : =,<,>,<>,>=,<=
         *
         * Example expressions are:
         *
         * "X+Y/2"
         * "SIN(X)+AVG(A,B,C)"
         * "SUM(X,Y,Z,K,L)/5"
         */

        void SetExpression(string_t expr);
       
        /**
         * Return the current expression string.
         */

        string_t GetExpression();

        /**
         *  VariableCallback is a function that is implemented by the user to provide values for undefined variables.
         *      If VariableCallback is set for the CMathParser instance, then the parser will
         *  tolerate undefined variables during parsing and it will invoke the user defined
         *  VariableCallback function to retrieve the variables values during evaluation.
         *  If VariableCallback is NULL, then the parser will require that all variables used in an expression
         *  are predefined before the parse operation.
         *  VariableCallback is useful in situations where the application domain is so large that
         *  defining every possible variable ahead of time is not possible.
         *  VariableCallback implementation should decide whether a variable name is valid and what it's
         *  value should be. If the variable name is not valid, then the VariableCallback should throw
         *  an exception and stop the expression evaluation.  
         *  VariableCallback typedef for the function signature is as follows:
         *  typedef _ValueT VariableCallback(CMathParser<_CharT, _ValueT> *pParentParser, const string_t varName);
         *  The user defined function takes two parameters:
         *  1. A pointer to the parser instance making this call.
         *  2. The variable name as a string.
         *  Return value shall be the desired value for this variable name.
         *  If the variable is not valid, then an exception should be thrown.
         *  CMathParser::ParserException is a good canditate to throw in such case.
         */

        void SetVariableCallback(PVariableCallback callbackFunction);

        /**
         *  See SetVariableCallback.
         */

        PVariableCallback GetVariableCallback();
       
        /**
         * Returns the list of currently defined functions as a vector of strings.
         */

        vector<string_t> GetDefinedFunctionNames();
       
        /**
         * Returns the list of currently defined variables as a vector of strings.
         */

        vector<string_t> GetDefinedVariableNames();
       
        /**
     * Returns the list of currently defined functions (and their respective param counts) as a map of strings and ints.
     */

    std::map<string_t, int> GetDefinedFunctionInfo();
}

#endif //__MATH_PARSER_H_
 

webmaster@bestcode.com