Antiprism 0.23

- Main Page
- Namespaces
- Classes
- Files

- Class List
- Class Hierarchy
- Class Members

Classes | Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Static Protected Attributes

# mu::ParserBase Class Reference

Mathematical expressions parser (base parser engine). More...

`#include <muParserBase.h>`

Inheritance diagram for mu::ParserBase:
[legend]
Collaboration diagram for mu::ParserBase:
[legend]

List of all members.

## Classes
class | change_dec_sep
| A facet class used to change decimal and thousands separator. More...
## Public Types
typedef ParserError | exception_type
| Type of the error class.
## Public Member Functions
| ParserBase ()
| Constructor.
| ParserBase (const ParserBase &a_Parser)
| Copy constructor.
ParserBase & | operator= (const ParserBase &a_Parser)
| Assignement operator.
value_type | Eval () const
| Calculate the result.
value_type * | Eval (int &nStackSize) const
| Evaluate an expression containing comma seperated subexpressions.
int | GetNumResults () const
| Return the number of results on the calculation stack.
void | SetExpr (const string_type &a_sExpr)
| Set the formula.
void | SetVarFactory (facfun_type a_pFactory, void *pUserData=NULL)
| Set a function that can create variable pointer for unknown expression variables.
void | SetDecSep (char_type cDecSep)
| Set the decimal separator.
void | SetThousandsSep (char_type cThousandsSep=0)
| Sets the thousands operator.
void | ResetLocale ()
| Resets the locale.
void | EnableOptimizer (bool a_bIsOn=true)
| Enable or disable the formula optimization feature.
void | EnableBuiltInOprt (bool a_bIsOn=true)
| Enable or disable the built in binary operators.
bool | HasBuiltInOprt () const
| Query status of built in variables.
void | AddValIdent (identfun_type a_pCallback)
| Add a value parsing function.
template<typename T >
void | DefineFun (const string_type &a_strName, T a_pFun, bool a_bAllowOpt=true)
| Define a parser function without arguments.
void | DefineOprt (const string_type &a_strName, fun_type2 a_pFun, unsigned a_iPri=0, EOprtAssociativity a_eAssociativity=oaLEFT, bool a_bAllowOpt=false)
| Define a binary operator.
void | DefineConst (const string_type &a_sName, value_type a_fVal)
| Add a user defined constant.
void | DefineStrConst (const string_type &a_sName, const string_type &a_strVal)
| Define a new string constant.
void | DefineVar (const string_type &a_sName, value_type *a_fVar)
| Add a user defined variable.
void | DefinePostfixOprt (const string_type &a_strFun, fun_type1 a_pOprt, bool a_bAllowOpt=true)
| Add a user defined operator.
void | DefineInfixOprt (const string_type &a_strName, fun_type1 a_pOprt, int a_iPrec=prINFIX, bool a_bAllowOpt=true)
| Add a user defined operator.
void | ClearVar ()
| Clear all user defined variables.
void | ClearFun ()
| Clear all functions.
void | ClearConst ()
| Clear all user defined constants.
void | ClearInfixOprt ()
| Clear the user defined Prefix operators.
void | ClearPostfixOprt ()
| Clear all user defined postfix operators.
void | ClearOprt ()
| Clear all user defined binary operators.
void | RemoveVar (const string_type &a_strVarName)
| Remove a variable from internal storage.
const varmap_type & | GetUsedVar () const
| Return a map containing the used variables only.
const varmap_type & | GetVar () const
| Return a map containing the used variables only.
const valmap_type & | GetConst () const
| Return a map containing all parser constants.
const string_type & | GetExpr () const
| Retrieve the formula.
const funmap_type & | GetFunDef () const
| Return prototypes of all parser functions.
string_type | GetVersion (EParserVersionInfo eInfo=pviFULL) const
| Returns the version of muparser.
const char_type ** | GetOprtDef () const
| Get the default symbols used for the built in operators.
void | DefineNameChars (const char_type *a_szCharset)
| Define the set of valid characters to be used in names of functions, variables, constants.
void | DefineOprtChars (const char_type *a_szCharset)
| Define the set of valid characters to be used in names of binary operators and postfix operators.
void | DefineInfixOprtChars (const char_type *a_szCharset)
| Define the set of valid characters to be used in names of infix operators.
const char_type * | ValidNameChars () const
| Virtual function that defines the characters allowed in name identifiers.
const char_type * | ValidOprtChars () const
| Virtual function that defines the characters allowed in operator definitions.
const char_type * | ValidInfixOprtChars () const
| Virtual function that defines the characters allowed in infix operator definitions.
void | SetArgSep (char_type cArgSep)
| Set argument separator.
char_type | GetArgSep () const
| Get the argument separator character.
void | Error (EErrorCodes a_iErrc, int a_iPos=(int) mu::string_type::npos, const string_type &a_strTok=string_type()) const
| Create an error containing the parse error position.
## Static Public Member Functions
static void | EnableDebugDump (bool bDumpCmd, bool bDumpStack)
| Enable the dumping of bytecode amd stack content on the console.
## Protected Member Functions
void | Init ()
| Initialize user defined functions.
## Static Protected Attributes
static const char_type * | c_DefaultOprt []
| Identifiers for built in binary operators.
static std::locale | s_locale = std::locale(std::locale::classic(), new change_dec_sep<char_type>('.'))
| The locale used by the parser.

## Detailed Description

Mathematical expressions parser (base parser engine).

Author:
  (C) 2012 Ingo Berg

This is the implementation of a bytecode based mathematical expressions parser. The formula will be parsed from string and converted into a bytecode. Future calculations will be done with the bytecode instead the formula string resulting in a significant performance increase. Complementary to a set of internally implemented functions the parser is able to handle user defined functions and variables.

## Member Typedef Documentation

typedef ParserError mu::ParserBase::exception_type

Type of the error class.

Included for backwards compatibility.

## Constructor & Destructor Documentation

mu::ParserBase::ParserBase | ( |  | ) |

Constructor.

Parameters:

  a_szFormula | the formula to interpret.

Exceptions:

  ParserException | if a_szFormula is null.

mu::ParserBase::ParserBase | ( | const ParserBase & | a_Parser | ) |

Copy constructor.

Tha parser can be safely copy constructed but the bytecode is reset during copy construction.

## Member Function Documentation

void mu::ParserBase::AddValIdent | ( | identfun_type | a_pCallback | ) |

Add a value parsing function.

When parsing an expression muParser tries to detect values in the expression string using different valident callbacks. Thuis it's possible to parse for hex values, binary values and floating point values.

void mu::ParserBase::ClearConst | ( |  | ) |

Clear all user defined constants.

Both numeric and string constants will be removed from the internal storage.

Postcondition:
  Resets the parser to string parsing mode.

Exceptions:

  nothrow |

void mu::ParserBase::ClearFun | ( |  | ) |

Clear all functions.

Postcondition:
  Resets the parser to string parsing mode.

Exceptions:

  nothrow |

void mu::ParserBase::ClearInfixOprt | ( |  | ) |

Clear the user defined Prefix operators.

Postcondition:
  Resets the parser to string parser mode.

Exceptions:

  nothrow |

void mu::ParserBase::ClearOprt | ( |  | ) |

Clear all user defined binary operators.

Postcondition:
  Resets the parser to string parsing mode.

Exceptions:

  nothrow |

void mu::ParserBase::ClearPostfixOprt | ( |  | ) |

Clear all user defined postfix operators.

Postcondition:
  Resets the parser to string parsing mode.

Exceptions:

  nothrow |

void mu::ParserBase::ClearVar | ( |  | ) |

Clear all user defined variables.

Exceptions:

  nothrow | Resets the parser to string parsing mode by calling #ReInit.

void mu::ParserBase::DefineConst | ( | const string_type & | a_sName,
|  | value_type | a_fVal
| ) |  |

Add a user defined constant.

Parameters:

  [in] | a_sName | The name of the constant.
  [in] | a_fVal | the value of the constant.

Postcondition:
  Will reset the Parser to string parsing mode.

Exceptions:

  ParserException | in case the name contains invalid signs.

template<typename T >

void mu::ParserBase::DefineFun | ( | const string_type & | a_strName,
|  | T | a_pFun,
|  | bool | a_bAllowOpt = `true`
| ) |  | `[inline]`

Define a parser function without arguments.

Parameters:

  a_strName | Name of the function
  a_pFun | Pointer to the callback function
  a_bAllowOpt | A flag indicating this function may be optimized

void mu::ParserBase::DefineInfixOprt | ( | const string_type & | a_sName,
|  | fun_type1 | a_pFun,
|  | int | a_iPrec = `prINFIX`,
|  | bool | a_bAllowOpt = `true`
| ) |  |

Add a user defined operator.

Postcondition:
  Will reset the Parser to string parsing mode.

Parameters:

  [in] | a_sName | operator Identifier
  [in] | a_pFun | Operator callback function
  [in] | a_iPrec | Operator Precedence (default=prSIGN)
  [in] | a_bAllowOpt | True if operator is volatile (default=false)

See also:
  EPrec

void mu::ParserBase::DefineOprt | ( | const string_type & | a_sName,
|  | fun_type2 | a_pFun,
|  | unsigned | a_iPrec = `0`,
|  | EOprtAssociativity | a_eAssociativity = `oaLEFT`,
|  | bool | a_bAllowOpt = `false`
| ) |  |

Define a binary operator.

Parameters:

  [in] | a_sName | The identifier of the operator.
  [in] | a_pFun | Pointer to the callback function.
  [in] | a_iPrec | Precedence of the operator.
  [in] | a_eAssociativity | The associativity of the operator.
  [in] | a_bAllowOpt | If this is true the operator may be optimized away.

Adds a new Binary operator the the parser instance.

void mu::ParserBase::DefinePostfixOprt | ( | const string_type & | a_sName,
|  | fun_type1 | a_pFun,
|  | bool | a_bAllowOpt = `true`
| ) |  |

Add a user defined operator.

Postcondition:
  Will reset the Parser to string parsing mode.

void mu::ParserBase::DefineStrConst | ( | const string_type & | a_strName,
|  | const string_type & | a_strVal
| ) |  |

Define a new string constant.

Parameters:

  [in] | a_strName | The name of the constant.
  [in] | a_strVal | the value of the constant.

void mu::ParserBase::DefineVar | ( | const string_type & | a_sName,
|  | value_type * | a_pVar
| ) |  |

Add a user defined variable.

Parameters:

  [in] | a_sName | the variable name
  [in] | a_pVar | A pointer to the variable vaule.

Postcondition:
  Will reset the Parser to string parsing mode.

Exceptions:

  ParserException | in case the name contains invalid signs or a_pVar is NULL.

void mu::ParserBase::EnableBuiltInOprt | ( | bool | a_bIsOn = `true` | ) |

Enable or disable the built in binary operators.

Exceptions:

  nothrow |

See also:
  m_bBuiltInOp, ReInit()

If you disable the built in binary operators there will be no binary operators defined. Thus you must add them manually one by one. It is not possible to disable built in operators selectively. This function will Reinitialize the parser by calling ReInit().

void mu::ParserBase::EnableDebugDump | ( | bool | bDumpCmd,
|  | bool | bDumpStack
| ) |  | `[static]`

Enable the dumping of bytecode amd stack content on the console.

Parameters:

  bDumpCmd | Flag to enable dumping of the current bytecode to the console.
  bDumpStack | Flag to enable dumping of the stack content is written to the console.

This function is for debug purposes only!

void mu::ParserBase::EnableOptimizer | ( | bool | a_bIsOn = `true` | ) |

Enable or disable the formula optimization feature.

Postcondition:
  Resets the parser to string parser mode.

Exceptions:

  nothrow |

void mu::ParserBase::Error | ( | EErrorCodes | a_iErrc,
|  | int | a_iPos = `(int)mu::string_type::npos`,
|  | const string_type & | a_sTok = `string_type()`
| ) |  | const

Create an error containing the parse error position.

This function will create an Parser Exception object containing the error text and its position.

Parameters:

  a_iErrc | [in] The error code of type EErrorCodes.
  a_iPos | [in] The position where the error was detected.
  a_strTok | [in] The token string representation associated with the error.

Exceptions:

  ParserException | always throws thats the only purpose of this function.

value_type * mu::ParserBase::Eval | ( | int & | nStackSize | ) | const

Evaluate an expression containing comma seperated subexpressions.

Parameters:

  [out] | nStackSize | The total number of results available

Returns:
  Pointer to the array containing all expression results

This member function can be used to retriev all results of an expression made up of multiple comma seperated subexpressions (i.e. "x+y,sin(x),cos(y)")

value_type mu::ParserBase::Eval | ( |  | ) | const

Calculate the result.

A note on const correctness: I consider it important that Calc is a const function. Due to caching operations Calc changes only the state of internal variables with one exception m_UsedVar this is reset during string parsing and accessible from the outside. Instead of making Calc non const GetUsedVar is non const because it explicitely calls Eval() forcing this update.

Precondition:
  A formula must be set.
  Variables must have been set (if needed)

See also:
  #m_pParseFormula

Returns:
  The evaluation result

Exceptions:

  ParseException | if no Formula is set or in case of any other error related to the formula.

const funmap_type & mu::ParserBase::GetFunDef | ( |  | ) | const

Return prototypes of all parser functions.

Returns:
  #m_FunDef

See also:
  FunProt

Exceptions:

  nothrow | The return type is a map of the public type funmap_type containing the prototype definitions for all numerical parser functions. String functions are not part of this map. The Prototype definition is encapsulated in objects of the class FunProt one per parser function each associated with function names via a map construct.

int mu::ParserBase::GetNumResults | ( |  | ) | const

Return the number of results on the calculation stack.

If the expression contains comma seperated subexpressions (i.e. "sin(y), x+y"). There mey be more than one return value. This function returns the number of available results.

const char_type ** mu::ParserBase::GetOprtDef | ( |  | ) | const

Get the default symbols used for the built in operators.

See also:
  c_DefaultOprt

string_type mu::ParserBase::GetVersion | ( | EParserVersionInfo | eInfo = `pviFULL` | ) | const

Returns the version of muparser.

Parameters:

  eInfo | A flag indicating whether the full version info should be returned or not.

Format is as follows: "MAJOR.MINOR (COMPILER_FLAGS)" The COMPILER_FLAGS are returned only if eInfo==pviFULL.

bool mu::ParserBase::HasBuiltInOprt | ( |  | ) | const

Query status of built in variables.

Returns:
  #m_bBuiltInOp; true if built in operators are enabled.

Exceptions:

  nothrow |

void mu::ParserBase::Init | ( |  | ) | `[protected]`

Initialize user defined functions.

Calls the virtual functions InitFun(), InitConst() and InitOprt().

ParserBase & mu::ParserBase::operator= | ( | const ParserBase & | a_Parser | ) |

Assignement operator.

Implemented by calling Assign(a_Parser). Self assignement is suppressed.

Parameters:

  a_Parser | Object to copy to this.

Returns:
  *this

Exceptions:

  nothrow |

void mu::ParserBase::RemoveVar | ( | const string_type & | a_strVarName | ) |

Remove a variable from internal storage.

Exceptions:

  nothrow | Removes a variable if it exists. If the Variable does not exist nothing will be done.

void mu::ParserBase::ResetLocale | ( |  | ) |

Resets the locale.

The default locale used "." as decimal separator, no thousands separator and "," as function argument separator.

void mu::ParserBase::SetArgSep | ( | char_type | cArgSep | ) |

Set argument separator.

Parameters:

  cArgSep | the argument separator character.

void mu::ParserBase::SetDecSep | ( | char_type | cDecSep | ) |

Set the decimal separator.

Parameters:

  cDecSep | Decimal separator as a character value.

See also:
  SetThousandsSep

By default muparser uses the "C" locale. The decimal separator of this locale is overwritten by the one provided here.

void mu::ParserBase::SetExpr | ( | const string_type & | a_sExpr | ) |

Set the formula.

Parameters:

  a_strFormula | Formula as string_type

Exceptions:

  ParserException | in case of syntax errors.

Triggers first time calculation thus the creation of the bytecode and scanning of used variables.

void mu::ParserBase::SetThousandsSep | ( | char_type | cThousandsSep = `0` | ) |

Sets the thousands operator.

Parameters:

  cThousandsSep | The thousands separator as a character

See also:
  SetDecSep

By default muparser uses the "C" locale. The thousands separator of this locale is overwritten by the one provided here.

void mu::ParserBase::SetVarFactory | ( | facfun_type | a_pFactory,
|  | void * | pUserData = `NULL`
| ) |  |

Set a function that can create variable pointer for unknown expression variables.

Parameters:

  a_pFactory | A pointer to the variable factory.
  pUserData | A user defined context pointer.

const char_type * mu::ParserBase::ValidInfixOprtChars | ( |  | ) | const

Virtual function that defines the characters allowed in infix operator definitions.

See also:
  ValidNameChars, ValidOprtChars

const char_type * mu::ParserBase::ValidNameChars | ( |  | ) | const

Virtual function that defines the characters allowed in name identifiers.

See also:
  ValidOprtChars, #ValidPrefixOprtChars

const char_type * mu::ParserBase::ValidOprtChars | ( |  | ) | const

Virtual function that defines the characters allowed in operator definitions.

See also:
  ValidNameChars, #ValidPrefixOprtChars

## Member Data Documentation

const char_type * mu::ParserBase::c_DefaultOprt`[static, protected]`

Initial value:

      {
        _T("<="), _T(">="),  _T("!="),
        _T("=="), _T("<"),   _T(">"),
        _T("+"),  _T("-"),   _T("*"),
        _T("/"),  _T("^"),   _T("&&"),
        _T("||"), _T("="),   _T("("),
        _T(")"),   _T("?"),  _T(":"), 0
      }

Identifiers for built in binary operators.

When defining custom binary operators with #AddOprt(...) make sure not to choose names conflicting with these definitions.

The documentation for this class was generated from the following files:

- base/muparser/muParserBase.h
- base/muparser/muParserBase.cc