bcParser.NET
Math Parser for .NET
Public Member Functions | Protected Attributes | Properties | List of all members
Bestcode.MathParser.MathParser Class Reference

MathParser class calculates the value of mathematical expressions given as strings at runtime. Expression can contain predefined or user defined variables and functions. More...

Inheritance diagram for Bestcode.MathParser.MathParser:
Bestcode.MathParser.StandardLib

Public Member Functions

 MathParser ()
 Constructor for the MathParser. Instances are not thread safe and should not be shared between threads without proper synchronization. More...
 
void Optimize ()
 Optimizes the parse tree by finding branches that evaluate to a constant and replacing them with a leaf representing the constant. Until the expression is changed and reparsed, further evaluation requests will be quicker.

If the same expression will not be evaluated repeatedly with varying values of parameters used in it, then optimization will not bring any gain, but will slow performance.

If OptimizationOn property is set to true, this method is called automatically when an evaluation is requested by calling Evaluate method or getValue() method. More...
 
Dictionary< string, string > GetTranslationStrings ()
 Returns the existing trasnlatable strings used to report error messages. To use this component in a localized application, set the translated versions of strings for each value that exists in the Dictionary. By default, same Dictionary is shared between all instances of the parser. To change translation strings, set a new Dictionary of your own for the parser instance instead of editing the values contained in this Dictionary if you do not wish other parser instances not to be effected. More...
 
void SetTranslationStrings (Dictionary< string, string > strings)
 Sets the key/value pairs where value is a translated message string for the parser to use while constructing messages. This mechanism allows the parser instances in the same VM efficiently use different locales independent of each other. not for each instance of the parser.

Messages may contain parameter placeholders. For example: "Variable {0} does not exist". You need to have your own messages translated accordingly.
More...
 
IConvertible GetVariable (String varName)
 Variable property is a way to set and get variable values. Throws Exception if the variable does not exist. Variable name is not case sensitive. More...
 
void SetVariable (String varName, String newVal, VariableDelegate valueProvider)
 Variable property is a way to set and get variable values. SetVariable function creates the variable if the variable does not exist. Variable name is not case sensitive. Throws exception if the variable needs to be created and the name is not a valid variable name. CreateVar is just an alias for this method. More...
 
void CreateConstant (String varName, double newVal)
 Creates a new constant that can be used in an expression. Once a constant is created, it's value cannot be changed. Constants make it possible to optimize constant branches of an expression. More...
 
void CreateConstant (String varName, String newVal)
 Creates a new constant that can be used in an expression. Once a constant is created, it's value cannot be changed. Constants make it possible to optimize constant branches of an expression. More...
 
IConvertible Evaluate ()
 Evaluates the expression and returns the result of it. If it cannot be parsed or evaluated then this method throws Exception.

Calling this method is identical to calling getValue() More...
 
void Parse ()
 Parses the expression and forms a parse tree. Throws Exception if it cannot parse. Upon successful completion of parsing, it will set the Dirty flag to false, so that unless the expression is changed or variables and functions added or removed, expression does not need to be re-parsed. Users may want to call the parse method directly to check the validity of an input expression using a try-except block.

If OptimizationOn property is true, Parse method will optimize the parse tree by evaluating constant branches of the parse tree at that moment, so that Evaluate function will run faster. More...
 
void CreateVar (String varName, String varValue, VariableDelegate valueProvider)
 Creates a variable with given name and initial value. If the variable already exists, sets it's value to the specified value. Throws Exception if varName is not a valid variable name. More...
 
void CreateFunc (String newFuncName, IFunction funcAddr)
 CreateFunc method creates a new function that takes n number of parameters (could be 0) in the parser's list of functions. If the function name already exists then this method throws Exception. Function name is not case sensitive.

The second parameter is a reference to an implementation of the handler interface:

interface IFunction {
public IConvertible Run(IParameter[] parameters);
public int GetNumberOfParams();
}

While evaluation of the expression, when the registered function name is encountered, the user supplied IFunction.Run(IParameter[]) will be called.

This event handler ( IFunction.Run(IParameter[]) ) will need to return a result (representing the value of the function) based on the parameters passed as an array of IParameter objects. If the number of parameters that a function takes is not known ahead of time, then the GetNumberOfParams function needs to return -1. Otherwise, it will return the number of parameters that will be passed to the function at runtime. Knowing the number of parameters ahead of time helps detect syntax errors during parsing. For example, if SIN(x) function descriptor did not tell us that it was taking only 1 parameter, then an expression like: SIN(x,y) would not cause syntax error during parsing, and if the implementation of SIN(x) did not check actual runtime number of parameters passed, then the problem could go undetected and the second y parameter could be ignored silently. More...
 
void CreateTwoParamFunc (String newFuncName, TwoParamFunc funcAddr)
 A shortcut for common case scenario. CreateTwoParamFunc method creates a new function that takes two parameters and returns a double value. This is a convenient alternative to the CreateFunc method. Using CreateTwoParamFunc you can use a .NET delegate to create your function where as using CreateFunc method you would have to have a class implement the IFunction interface. Under the covers, CreateTwoParamFunc employs an adapter class that implements IFunction interface and calls your delegate as needed.

The second parameter is of type delegate TwoParamFunc:

public delegate double TwoParamFunc(IParameter x, IParameter y);

While evaluation of the expression, when the registered function name is encountered, the user supplied TwoParamFunc(IParameter x, IParameter y) will be called.

This delegate ( TwoParamFunc(IParameter x, IParameter y) ) will need to return a result (representing the value of the function) based on the x and y parameters. More...
 
void CreateOneParamFunc (String newFuncName, OneParamFunc funcAddr)
 A shortcut for common case scenario. CreateOneParamFunc method creates a new function that takes one parameter and returns a double value. This is a convenient alternative to the CreateFunc method. Using CreateOneParamFunc you can use a .NET delegate to create your function where as using CreateFunc method you would have to have a class implement the IFunction interface. Under the covers, CreateOneParamFunc employs an adapter class that implements IFunction interface and calls your delegate as needed.

The second parameter is a reference to an implementation of the handler interface:

public delegate double OneParamFunc(IParameter x);

While evaluation of the expression, when the registered function name is encountered, the user supplied OneParamFunc.run(Parameter x) will be called.

This event handler ( OneParamFunc.run(Parameter x) ) will need to return a result (representing the value of the function) based on the x parameter. More...
 
void CreateDefaultFuncs ()
 CreateDefaultFuncs method creates some predefined functions in the parser's list of functions.

Predefined functions 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

VAL: VAL("3.1") = 3.1 Returns the floating point numeric value of the string argument.

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

MAX: MAX(2, 3) is 3.

IF: The IF(b, case1, case2) function provides branching capability. If b is not 0, then it returns case1, else it returns case2. Behavior is similar to C#'s: return b ? case1 : case2;
If b==0 then case1 will not be Evaluated, and vice versa. Example: IF(HEIGHT, 3/HEIGHT, 3) will make sure 3/HEIGHT does not cause division by zero.

Predefined functions that take no parameters are: RND: RND() function generates a random number (double value) between 0 and 1.

STR: STR(123) function returns the string representation of the passed value: "123".

SUBSTR: SUBSTR("Hello", 1,3) function returns the substring just like C# String.Substring function. The first parameter is the string, the second parameter is which index (0 based) to start copying, and the last parameter is the number of characters to copy. For example, SUBSTR("Hello", 1,3) returns "ell".

STRLEN: STRLEN("abc") function returns the length of the string parameter. For example, for "abc" it returns 3.

CONCAT: CONCAT("abc","def",...) function returns the concatanated strings: "abcdef". There is no preset limit on the number of parameters.

TRIM: TRIM(" abc ") function returns the trimmed version of the string parameter: " abc " -> "abc".

SUM: SUM(2,3,5,...) functions returns the sum of it's arguments. There is no preset limit on the number of parameters.

User functions can be added using CreateFunc method. Functions and Variables can be deleted using DeleteVar, DeleteFunc, DeleteAllVars, DeleteAllFuncs methods. More...
 
void CreateDefaultVars ()
 X, Y and PI variables are predefined and can be immediately used in the expression. Initial values of X and Y are 0. PI is 3.14159265358979 More...
 
void DeleteVar (String varName)
 DeleteVar method deletes an existing variable from the list of available variables. If the variable does not exist, then DeleteVar does nothing.

When a variable is deleted Dirty flag is set to true so that next time the Evaluate function is called the expression will be reparsed. Variable name is not case sensitive. More...
 
void DeleteFunc (String funcName)
 DeleteFunc method deletes an existing function from the list of available functions. If the function does not exist, deleteFunc does nothing.

When a function is deleted Dirty flag is set to true so that next time the Evaluate function is called the expression will be reparsed. Function name is not case sensitive. More...
 
void DeleteAllVars ()
 DeleteAllVars method deletes all variables from the list of available variables.

This action may be useful when number of unused variables is too high that causes performance to degrade.

When a variable is deleted Dirty flag is set to true so that next time the Evaluate function is called the expression will be reparsed. More...
 
void DeleteAllFuncs ()
 DeleteAllFuncs method deletes all variables from the list of available functions.

This action may be useful when number of unused functions is too high that causes performance to degrade.

When a function is deleted Dirty flag is set to true so that next time the Evaluate function is called the expression will be reparsed. More...
 
void FreeParseTree ()
 FreeParseTree can be explicitly called to free the resources taken by the allocated Parse tree when an expression is parsed. FreeParseTree sets the Dirty flag to true so that next time the Evaluate function is called, expression will be parsed forming a new, valid parse tree to be evaluated. More...
 
bool IsVariableUsed (String varName)
 Returns true if a variable with the name 'varName' is used in the current expression. Variable name is not case sensitive. Throws exception if expression is not parsed and cannot be parsed. More...
 
bool IsFunctionUsed (String funcName)
 Returns true if a function with the name 'funcName' is used in the current expression. Function name is not case sensitive. Throws exception if expression is not parsed and cannot be parsed. More...
 
bool IsVariable (String varName)
 Returns true if a variable with the name 'varName' is present in the current variables list. For backward compatibility, IsVariable returns true for constants also. For constants, you can use IsConstant. More...
 
bool IsConstant (String constName)
 Returns true if a constant with the name 'constName' is defined. More...
 
bool IsFunction (String funcName)
 Returns true if a function with the name 'funcName' is present in any of the current functions lists. More...
 
IList< string > GetVariablesUsed ()
 Returns the list of variables used in the current expression as an array of Strings. Each element of the array is guaranteed not to be null. If variables are not defined ahead of time, then VariableResolver must have been set. Otherwise, when an undefined variable is found in the expression, ParserException will be thrown. More...
 
String[] GetVariables ()
 Returns the list of variables as an array of Strings. Each element of the array is guaranteed not to be null. More...
 
String[] GetFunctions ()
 Returns a String[] array of function names declared for this parser. Elements of the array are guaranteed not to be null. More...
 

Protected Attributes

String m_Expression
 protected variable that holds the expression to parse. More...
 
bool m_Dirty
 non-public flag that shows if parsing is needed or not. if false, existing parse tree will be re-used. More...
 
bool m_OptimizationOn
 when optimization on, after the parse tree is compiled, it will be further optimized by removing sub branches that evaluate to a constant. This will make Parse() operation slower and GetValue() operation faster. More...
 
Dictionary< string, IFunctionm_Functions
 internal list of functions that take more than 2 parameters that are available for use in an expression. More...
 
CultureInfo m_CultureInfo = CultureInfo.InvariantCulture
 Current CultureInfo for this parser instance. Default is InvariantCulture. Setting this and setting CultureSpecificDecimals causes decimal separator char to be dot(.) or comma(,) depending on CultureInfo. More...
 
bool m_PrecedingZerosAllowed = false
 Allow preceding zeros or not? Default is false. 05 is valid if property is true. More...
 
bool m_StringLiteralsAllowed = true
 Does the expression allows string literals or not? For example, is an expression like this allowed: "Hello"+"World" More...
 
STR_CONCAT_OP m_StrConcatOperator
 The parser can use ampersand(&) or the plus(+) operator for string concatenations. You can set which one you want using StrConcatOperator property. The default is ampersand(&). Valid values are STR_CONCAT_OP.PLUS or STR_CONCAT_OP.AMPERSAND. More...
 
TwoParameterFunc m_AddOp = add_
 Implementation of + operator. More...
 
TwoParameterFunc m_AndOp = andWithStr_
 Implementation of & operator for strings. More...
 

Properties

bool CultureSpecificDecimals [get, set]
 If false (default), decimal separator is always dot (.) regardless of CultureInfo property. If true, CultureInfo property decides whether dot or comma is used. If comma is being used, then function parameter separator is colon (:). More...
 
char DecimalSeparator [get]
 The decimal separator that is currently in effect. This value is determined by CultureSpecificDecimals property and CultureInfo property. By default it is dot (.), and depending on CultureInfo that is set, it can be comma (,) if CultureSpecificDecimals is set to true. If comma is being used, then FunctionParamSeparator is colon (:). More...
 
char FunctionParamSeparator [get]
 Function parameters are by default separated by comma (,). But colon (:) can be used as well. This value is determined by CultureSpecificDecimals property and CultureInfo property. If CultureSpecificDecimals is set to true and if comma is being used as a decimal separator then FunctionParamSeparatoI is colon (:), otherwise it is comma (,). More...
 
STR_CONCAT_OP StrConcatOperator [get, set]
 The parser can use ampersand(&) or the plus(+) operator for string concatenations. You can set which one you want using StrConcatOperator property. The default is ampersand(&). Valid values are STR_CONCAT_OP.PLUS or STR_CONCAT_OP.AMPERSAND. More...
 
CultureInfo CultureInfo [get, set]
 CultureInfo is used to sort list of variable names, function names when requuested as an array. More...
 
bool StringLiteralsAllowed [get, set]
 Can the expression contain string literals such as "abc", "hello world" etc. If you do not want to support strings in the expression, (want numeric processing only), then you can set this property to false and then you can also remove string functions from the list of available functions. Then the parser will solely work on numeric expressions. The string literals may also be useful in numeric context where the string can refer to a database table or column name and can be passed to functions that actually use these strings to lookup these values in databases to return numeric values too. More...
 
bool PrecedingZerosAllowed [get, set]
 Is 05 a valid number or not? By default it is not. If this property is set to true, then it is valid. More...
 
VariableDelegate VariableResolver [get, set]
 VariableResolver delegate is used as a callback function that returns the values of variables when asked. This is useful when a variable cannot be defined before the parse operation. If VariableResolver property is set, it will be used to resolve variables that were not defined at the time parse operation has started. This means that syntax errors regarding undefined variables will not be caught at parse time. This VariableResolver (user implementation) will decide whether a variable name is valid or not. This is useful when for example the value comes from a database lookup. In some cases, the problem domain is too big to define the variables ahead of time. In such cases, it makes sense to parse with the assumption that it is a valid variable and resolve it's value when needed on demand during evaluation. More...
 
IConvertible X [get, set]
 X property represents the X variable used in the mathematical expression which was input to be evaluated. You can set the X variable to a numeric or a string value and call the Parse method (or Value property) to retrieve the new result of the expression. X variable is created by default for the convenience of the user. Additional variables can be added by using the CreateVar method. Variable names are case insensitive. Throws Exception if variable X does not exist (was removed). More...
 
IConvertible Y [get, set]
 Y property represents the Y variable used in the mathematical expression which was input to be evaluated. You can set the Y variable to a numeric or a string value and call the Parse method (or Value property) to retrieve the new result of the expression. Y variable is created by default for the convenience of the user. Additional variables can be added by using the CreateVar method. Variable names are case insensitive. Throws Exception if variable Y does not exist (was removed). More...
 
IConvertible Value [get]
 Value property is a read only property which returns the result of the expression. throws Exception if expression cannot be parsed. Return value is an IConvertible that can be converted to either Double or String using Convert class. More...
 
double ValueAsDouble [get]
 Value property is a read only property which returns the result of the expression. throws Exception if expression cannot be parsed. Return value is an IConvertible that is a Double. More...
 
String ValueAsString [get]
 Value property is a read only property which returns the result of the expression. throws Exception if expression cannot be parsed. Return value is an IConvertible that is a Double. More...
 
String Expression [get, set]
 Expression property represents the mathematical expression which is input to be Evaluated by the user. More...
 
bool OptimizationOn [get, set]
 Set OptimizationOn to let the bcParser component evaluate constant expressions at parse time. The optimized parse tree will enhance subsequant evaluation operations, though initial parsing will be slower.

Optimization is good if you are going to parse once and evaluate the same expression many many times with different variable values. More...
 

Detailed Description

MathParser class calculates the value of mathematical expressions given as strings at runtime. Expression can contain predefined or user defined variables and functions.

Constructor & Destructor Documentation

Bestcode.MathParser.MathParser.MathParser ( )

Constructor for the MathParser. Instances are not thread safe and should not be shared between threads without proper synchronization.

Member Function Documentation

void Bestcode.MathParser.MathParser.CreateConstant ( String  varName,
double  newVal 
)

Creates a new constant that can be used in an expression. Once a constant is created, it's value cannot be changed. Constants make it possible to optimize constant branches of an expression.

Parameters
varNameThe name of this constant.
newVala double value
void Bestcode.MathParser.MathParser.CreateConstant ( String  varName,
String  newVal 
)

Creates a new constant that can be used in an expression. Once a constant is created, it's value cannot be changed. Constants make it possible to optimize constant branches of an expression.

Parameters
varNameThe name of this constant.
newVala String
void Bestcode.MathParser.MathParser.CreateDefaultFuncs ( )

CreateDefaultFuncs method creates some predefined functions in the parser's list of functions.

Predefined functions 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

VAL: VAL("3.1") = 3.1 Returns the floating point numeric value of the string argument.

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

MAX: MAX(2, 3) is 3.

IF: The IF(b, case1, case2) function provides branching capability. If b is not 0, then it returns case1, else it returns case2. Behavior is similar to C#'s: return b ? case1 : case2;
If b==0 then case1 will not be Evaluated, and vice versa. Example: IF(HEIGHT, 3/HEIGHT, 3) will make sure 3/HEIGHT does not cause division by zero.

Predefined functions that take no parameters are: RND: RND() function generates a random number (double value) between 0 and 1.

STR: STR(123) function returns the string representation of the passed value: "123".

SUBSTR: SUBSTR("Hello", 1,3) function returns the substring just like C# String.Substring function. The first parameter is the string, the second parameter is which index (0 based) to start copying, and the last parameter is the number of characters to copy. For example, SUBSTR("Hello", 1,3) returns "ell".

STRLEN: STRLEN("abc") function returns the length of the string parameter. For example, for "abc" it returns 3.

CONCAT: CONCAT("abc","def",...) function returns the concatanated strings: "abcdef". There is no preset limit on the number of parameters.

TRIM: TRIM(" abc ") function returns the trimmed version of the string parameter: " abc " -> "abc".

SUM: SUM(2,3,5,...) functions returns the sum of it's arguments. There is no preset limit on the number of parameters.

User functions can be added using CreateFunc method. Functions and Variables can be deleted using DeleteVar, DeleteFunc, DeleteAllVars, DeleteAllFuncs methods.

void Bestcode.MathParser.MathParser.CreateDefaultVars ( )

X, Y and PI variables are predefined and can be immediately used in the expression. Initial values of X and Y are 0. PI is 3.14159265358979

void Bestcode.MathParser.MathParser.CreateFunc ( String  newFuncName,
IFunction  funcAddr 
)

CreateFunc method creates a new function that takes n number of parameters (could be 0) in the parser's list of functions. If the function name already exists then this method throws Exception. Function name is not case sensitive.

The second parameter is a reference to an implementation of the handler interface:

interface IFunction {
public IConvertible Run(IParameter[] parameters);
public int GetNumberOfParams();
}

While evaluation of the expression, when the registered function name is encountered, the user supplied IFunction.Run(IParameter[]) will be called.

This event handler ( IFunction.Run(IParameter[]) ) will need to return a result (representing the value of the function) based on the parameters passed as an array of IParameter objects. If the number of parameters that a function takes is not known ahead of time, then the GetNumberOfParams function needs to return -1. Otherwise, it will return the number of parameters that will be passed to the function at runtime. Knowing the number of parameters ahead of time helps detect syntax errors during parsing. For example, if SIN(x) function descriptor did not tell us that it was taking only 1 parameter, then an expression like: SIN(x,y) would not cause syntax error during parsing, and if the implementation of SIN(x) did not check actual runtime number of parameters passed, then the problem could go undetected and the second y parameter could be ignored silently.

Parameters
newFuncNameName of the new function to create.
funcAddrImplementation of the IFunction interface that will be invoked using IFunction.run(IParameter[]) when parser needs to execute this user defined function.
void Bestcode.MathParser.MathParser.CreateOneParamFunc ( String  newFuncName,
OneParamFunc  funcAddr 
)

A shortcut for common case scenario. CreateOneParamFunc method creates a new function that takes one parameter and returns a double value. This is a convenient alternative to the CreateFunc method. Using CreateOneParamFunc you can use a .NET delegate to create your function where as using CreateFunc method you would have to have a class implement the IFunction interface. Under the covers, CreateOneParamFunc employs an adapter class that implements IFunction interface and calls your delegate as needed.

The second parameter is a reference to an implementation of the handler interface:

public delegate double OneParamFunc(IParameter x);

While evaluation of the expression, when the registered function name is encountered, the user supplied OneParamFunc.run(Parameter x) will be called.

This event handler ( OneParamFunc.run(Parameter x) ) will need to return a result (representing the value of the function) based on the x parameter.

Parameters
newFuncNameName of the new function to create.
funcAddrDelegate that will be invoked when parser needs to execute this user defined function.
void Bestcode.MathParser.MathParser.CreateTwoParamFunc ( String  newFuncName,
TwoParamFunc  funcAddr 
)

A shortcut for common case scenario. CreateTwoParamFunc method creates a new function that takes two parameters and returns a double value. This is a convenient alternative to the CreateFunc method. Using CreateTwoParamFunc you can use a .NET delegate to create your function where as using CreateFunc method you would have to have a class implement the IFunction interface. Under the covers, CreateTwoParamFunc employs an adapter class that implements IFunction interface and calls your delegate as needed.

The second parameter is of type delegate TwoParamFunc:

public delegate double TwoParamFunc(IParameter x, IParameter y);

While evaluation of the expression, when the registered function name is encountered, the user supplied TwoParamFunc(IParameter x, IParameter y) will be called.

This delegate ( TwoParamFunc(IParameter x, IParameter y) ) will need to return a result (representing the value of the function) based on the x and y parameters.

Parameters
newFuncNameName of the new function to create.
funcAddrDelegate that will be invoked when parser needs to execute this user defined function.
void Bestcode.MathParser.MathParser.CreateVar ( String  varName,
String  varValue,
VariableDelegate  valueProvider 
)

Creates a variable with given name and initial value. If the variable already exists, sets it's value to the specified value. Throws Exception if varName is not a valid variable name.

Parameters
varNameVariable name (case insensitive).
varValueInitial value for the variable.
valueProviderThe callback delegate that decides the value of the variable at runtime.

public delegate IConvertible VariableDelegate(MathParser parser, String varName);

void Bestcode.MathParser.MathParser.DeleteAllFuncs ( )

DeleteAllFuncs method deletes all variables from the list of available functions.

This action may be useful when number of unused functions is too high that causes performance to degrade.

When a function is deleted Dirty flag is set to true so that next time the Evaluate function is called the expression will be reparsed.

void Bestcode.MathParser.MathParser.DeleteAllVars ( )

DeleteAllVars method deletes all variables from the list of available variables.

This action may be useful when number of unused variables is too high that causes performance to degrade.

When a variable is deleted Dirty flag is set to true so that next time the Evaluate function is called the expression will be reparsed.

void Bestcode.MathParser.MathParser.DeleteFunc ( String  funcName)

DeleteFunc method deletes an existing function from the list of available functions. If the function does not exist, deleteFunc does nothing.

When a function is deleted Dirty flag is set to true so that next time the Evaluate function is called the expression will be reparsed. Function name is not case sensitive.

Parameters
funcNameName of the function to delete.
void Bestcode.MathParser.MathParser.DeleteVar ( String  varName)

DeleteVar method deletes an existing variable from the list of available variables. If the variable does not exist, then DeleteVar does nothing.

When a variable is deleted Dirty flag is set to true so that next time the Evaluate function is called the expression will be reparsed. Variable name is not case sensitive.

Parameters
varNameName of the variable to delete.
IConvertible Bestcode.MathParser.MathParser.Evaluate ( )

Evaluates the expression and returns the result of it. If it cannot be parsed or evaluated then this method throws Exception.

Calling this method is identical to calling getValue()

<return>Returns the value of the parsed expression. The return type is an IConvertible that can be interpreted as either Double or String using the Convert class.</return>

void Bestcode.MathParser.MathParser.FreeParseTree ( )

FreeParseTree can be explicitly called to free the resources taken by the allocated Parse tree when an expression is parsed. FreeParseTree sets the Dirty flag to true so that next time the Evaluate function is called, expression will be parsed forming a new, valid parse tree to be evaluated.

String [] Bestcode.MathParser.MathParser.GetFunctions ( )

Returns a String[] array of function names declared for this parser. Elements of the array are guaranteed not to be null.

Returns
Array of function names that are currently defined for this parser instance.
Dictionary<string, string> Bestcode.MathParser.MathParser.GetTranslationStrings ( )

Returns the existing trasnlatable strings used to report error messages. To use this component in a localized application, set the translated versions of strings for each value that exists in the Dictionary. By default, same Dictionary is shared between all instances of the parser. To change translation strings, set a new Dictionary of your own for the parser instance instead of editing the values contained in this Dictionary if you do not wish other parser instances not to be effected.

Returns
Dictionary of key/value pairs where value is a Locale dependent, typically translated String, that may contain placeholder parameters like {0}, {1} etc.
IConvertible Bestcode.MathParser.MathParser.GetVariable ( String  varName)

Variable property is a way to set and get variable values. Throws Exception if the variable does not exist. Variable name is not case sensitive.

<return>Returns the current value of the variable. It is either Double or String</return>

String [] Bestcode.MathParser.MathParser.GetVariables ( )

Returns the list of variables as an array of Strings. Each element of the array is guaranteed not to be null.

Returns
Array of variable names that are currently defined for this parser instance.
IList<string> Bestcode.MathParser.MathParser.GetVariablesUsed ( )

Returns the list of variables used in the current expression as an array of Strings. Each element of the array is guaranteed not to be null. If variables are not defined ahead of time, then VariableResolver must have been set. Otherwise, when an undefined variable is found in the expression, ParserException will be thrown.

Returns
Array of variable names that are currently defined for this parser instance.
bool Bestcode.MathParser.MathParser.IsConstant ( String  constName)

Returns true if a constant with the name 'constName' is defined.

Parameters
constNameName of the constant in question.
Returns
Returns true if the constant exists in the list of variables of the parser instance. false otherwise.
bool Bestcode.MathParser.MathParser.IsFunction ( String  funcName)

Returns true if a function with the name 'funcName' is present in any of the current functions lists.

Parameters
funcNameName of the function in question.
Returns
Returns true if a function with the given name is defined. False otherwise.
bool Bestcode.MathParser.MathParser.IsFunctionUsed ( String  funcName)

Returns true if a function with the name 'funcName' is used in the current expression. Function name is not case sensitive. Throws exception if expression is not parsed and cannot be parsed.

Parameters
funcNameName of the function in question.
Returns
Returns true if the function with the given name was actually used in the current expression. Returns false otherwise.
bool Bestcode.MathParser.MathParser.IsVariable ( String  varName)

Returns true if a variable with the name 'varName' is present in the current variables list. For backward compatibility, IsVariable returns true for constants also. For constants, you can use IsConstant.

Parameters
varNameName of the variable in question.
Returns
Returns true if the variable exists in the list of variables of the parser instance. false otherwise.
bool Bestcode.MathParser.MathParser.IsVariableUsed ( String  varName)

Returns true if a variable with the name 'varName' is used in the current expression. Variable name is not case sensitive. Throws exception if expression is not parsed and cannot be parsed.

Parameters
varNameName of the variable in question.
Returns
Returns true if the variable with the given name was actually used in the current expression. Returns false otherwise.
void Bestcode.MathParser.MathParser.Optimize ( )

Optimizes the parse tree by finding branches that evaluate to a constant and replacing them with a leaf representing the constant. Until the expression is changed and reparsed, further evaluation requests will be quicker.

If the same expression will not be evaluated repeatedly with varying values of parameters used in it, then optimization will not bring any gain, but will slow performance.

If OptimizationOn property is set to true, this method is called automatically when an evaluation is requested by calling Evaluate method or getValue() method.

void Bestcode.MathParser.MathParser.Parse ( )

Parses the expression and forms a parse tree. Throws Exception if it cannot parse. Upon successful completion of parsing, it will set the Dirty flag to false, so that unless the expression is changed or variables and functions added or removed, expression does not need to be re-parsed. Users may want to call the parse method directly to check the validity of an input expression using a try-except block.

If OptimizationOn property is true, Parse method will optimize the parse tree by evaluating constant branches of the parse tree at that moment, so that Evaluate function will run faster.

void Bestcode.MathParser.MathParser.SetTranslationStrings ( Dictionary< string, string >  strings)

Sets the key/value pairs where value is a translated message string for the parser to use while constructing messages. This mechanism allows the parser instances in the same VM efficiently use different locales independent of each other. not for each instance of the parser.

Messages may contain parameter placeholders. For example: "Variable {0} does not exist". You need to have your own messages translated accordingly.

Existing strings are:

("ExpEmpty", "Expression is empty.");
("VarNtExst", "Variable {0} does not exist.");
("VarNtDbl", "Variable {0} is not numeric.");
("VarNtStr", "Variable {0} is not a string.");
("VarNtDblStr", "Variable {0} should be a Double or a String.");
("NtVarNm", "{0} is not a valid variable name.");
("SntxErr", "Syntax error in expression {0}");
("NtFncNm", "{0} is not a valid function name.");
("FncExst", "Function {0} already exists.");
("WrngNPrms", "Function {0} must accept at least 2 parameters not {1}.");
("ExpNtVld", "Sub expression &lt;{0}> in &lt;{1}> is not valid.");
("InvNPrm", "Invalid number of parameters in &lt;{0}>.");

Parameters
stringsDictionary of translated values hashed by key.
void Bestcode.MathParser.MathParser.SetVariable ( String  varName,
String  newVal,
VariableDelegate  valueProvider 
)

Variable property is a way to set and get variable values. SetVariable function creates the variable if the variable does not exist. Variable name is not case sensitive. Throws exception if the variable needs to be created and the name is not a valid variable name. CreateVar is just an alias for this method.

Parameters
newValNew value of the variable. It should be either a Double or a String.
varNameName of the variable whose value is being set.
valueProviderThe delegate that returns the value for a variable when asked by name. When a valueProvider is set for a Variable, it's assigned value wil lnot be used and instead the valueProvider of type

public delegate IConvertible VariableDelegate(MathParser parser, String varName);

will be called. This is useful in cases when the value of a variable comes from a database and it is not easy to set it's value (or it is costly) ahead of time. So, when you want to compute the variable value only when it is needed, then you can register a valueProvider to be called. You can use the same valueProvider for all or some of your variables or you can have a different valueProvider for each variable.

Member Data Documentation

TwoParameterFunc Bestcode.MathParser.MathParser.m_AddOp = add_
protected

Implementation of + operator.

TwoParameterFunc Bestcode.MathParser.MathParser.m_AndOp = andWithStr_
protected

Implementation of & operator for strings.

CultureInfo Bestcode.MathParser.MathParser.m_CultureInfo = CultureInfo.InvariantCulture
protected

Current CultureInfo for this parser instance. Default is InvariantCulture. Setting this and setting CultureSpecificDecimals causes decimal separator char to be dot(.) or comma(,) depending on CultureInfo.

bool Bestcode.MathParser.MathParser.m_Dirty
protected

non-public flag that shows if parsing is needed or not. if false, existing parse tree will be re-used.

String Bestcode.MathParser.MathParser.m_Expression
protected

protected variable that holds the expression to parse.

Dictionary<string, IFunction> Bestcode.MathParser.MathParser.m_Functions
protected

internal list of functions that take more than 2 parameters that are available for use in an expression.

bool Bestcode.MathParser.MathParser.m_OptimizationOn
protected

when optimization on, after the parse tree is compiled, it will be further optimized by removing sub branches that evaluate to a constant. This will make Parse() operation slower and GetValue() operation faster.

bool Bestcode.MathParser.MathParser.m_PrecedingZerosAllowed = false
protected

Allow preceding zeros or not? Default is false. 05 is valid if property is true.

STR_CONCAT_OP Bestcode.MathParser.MathParser.m_StrConcatOperator
protected

The parser can use ampersand(&) or the plus(+) operator for string concatenations. You can set which one you want using StrConcatOperator property. The default is ampersand(&). Valid values are STR_CONCAT_OP.PLUS or STR_CONCAT_OP.AMPERSAND.

bool Bestcode.MathParser.MathParser.m_StringLiteralsAllowed = true
protected

Does the expression allows string literals or not? For example, is an expression like this allowed: "Hello"+"World"

Property Documentation

CultureInfo Bestcode.MathParser.MathParser.CultureInfo
getset

CultureInfo is used to sort list of variable names, function names when requuested as an array.

bool Bestcode.MathParser.MathParser.CultureSpecificDecimals
getset

If false (default), decimal separator is always dot (.) regardless of CultureInfo property. If true, CultureInfo property decides whether dot or comma is used. If comma is being used, then function parameter separator is colon (:).

char Bestcode.MathParser.MathParser.DecimalSeparator
get

The decimal separator that is currently in effect. This value is determined by CultureSpecificDecimals property and CultureInfo property. By default it is dot (.), and depending on CultureInfo that is set, it can be comma (,) if CultureSpecificDecimals is set to true. If comma is being used, then FunctionParamSeparator is colon (:).

String Bestcode.MathParser.MathParser.Expression
getset

Expression property represents the mathematical expression which is input to be Evaluated by the user.

The expression can contain variables and/or constants such as X, Y, T, HEIGHT, WEIGHT and so on. The values of these constants are set before the expression is evaluated. The values of the variables can be set before the expression is evaluated or the values can be provided during evaluation using a delegate ValueProvider.



public delegate IConvertible VariableDelegate(MathParser parser, String varName);

Expression can also contain functions that take any number of parameters. Variable and Function names are not case sensitive.

When Expression is assigned a value, it becomes 'dirty' and further attempt to Evaluate its value will require it to be Parsed. But once it is Parsed, and a Parse tree representing the expression is formed, it won't be Parsed again, until it is assignd a new string (or another relevant change occurs). Instead, the Parse tree will be used to retrieve current results as the values of variables change.

X, Y and PI variables are predefined and can be immediately used in the expression. CreateVar, SetVariable methods can be used to add user variables.

Predefined functions 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

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

MAX: MAX(2, 3) is 3.

IF: The IF(b, case1, case2) function provides branching capability. If b is not 0, then it returns case1, else it returns case2. Behavior is similar to C#'s: return b ? case1 : case2;
If b==0 then case1 will not be Evaluated, and vice versa. Example: IF(HEIGHT, 3/HEIGHT, 3) will make sure 3/HEIGHT does not cause division by zero.

Predefined functions that take no parameters are: RND: RND() function generates a random number (double value) between 0 and 1.

STR: STR(123) function returns the string representation of the passed value: "123".

SUBSTR: SUBSTR("Hello", 1,3) function returns the substring just like C# String.Substring function. The first parameter is the string, the second parameter is which index (0 based) to start copying, and the last parameter is the number of characters to copy. For example, SUBSTR("Hello", 1,3) returns "ell".

STRLEN: STRLEN("abc") function returns the length of the string parameter. For example, for "abc" it returns 3.

CONCAT: CONCAT("abc","def",...) function returns the concatanated strings: "abcdef". There is no preset limit on the number of parameters.

SUM: SUM(2,3,5,...) functions returns the sum of it's arguments. There is no preset limit on the number of parameters.

User functions can be added using CreateFunc method. Functions and Variables can be deleted using DeleteVar, DeleteFunc, DeleteAllVars, DeleteAllFuncs methods.

char Bestcode.MathParser.MathParser.FunctionParamSeparator
get

Function parameters are by default separated by comma (,). But colon (:) can be used as well. This value is determined by CultureSpecificDecimals property and CultureInfo property. If CultureSpecificDecimals is set to true and if comma is being used as a decimal separator then FunctionParamSeparatoI is colon (:), otherwise it is comma (,).

bool Bestcode.MathParser.MathParser.OptimizationOn
getset

Set OptimizationOn to let the bcParser component evaluate constant expressions at parse time. The optimized parse tree will enhance subsequant evaluation operations, though initial parsing will be slower.

Optimization is good if you are going to parse once and evaluate the same expression many many times with different variable values.

bool Bestcode.MathParser.MathParser.PrecedingZerosAllowed
getset

Is 05 a valid number or not? By default it is not. If this property is set to true, then it is valid.

STR_CONCAT_OP Bestcode.MathParser.MathParser.StrConcatOperator
getset

The parser can use ampersand(&) or the plus(+) operator for string concatenations. You can set which one you want using StrConcatOperator property. The default is ampersand(&). Valid values are STR_CONCAT_OP.PLUS or STR_CONCAT_OP.AMPERSAND.

bool Bestcode.MathParser.MathParser.StringLiteralsAllowed
getset

Can the expression contain string literals such as "abc", "hello world" etc. If you do not want to support strings in the expression, (want numeric processing only), then you can set this property to false and then you can also remove string functions from the list of available functions. Then the parser will solely work on numeric expressions. The string literals may also be useful in numeric context where the string can refer to a database table or column name and can be passed to functions that actually use these strings to lookup these values in databases to return numeric values too.

IConvertible Bestcode.MathParser.MathParser.Value
get

Value property is a read only property which returns the result of the expression. throws Exception if expression cannot be parsed. Return value is an IConvertible that can be converted to either Double or String using Convert class.

double Bestcode.MathParser.MathParser.ValueAsDouble
get

Value property is a read only property which returns the result of the expression. throws Exception if expression cannot be parsed. Return value is an IConvertible that is a Double.

String Bestcode.MathParser.MathParser.ValueAsString
get

Value property is a read only property which returns the result of the expression. throws Exception if expression cannot be parsed. Return value is an IConvertible that is a Double.

VariableDelegate Bestcode.MathParser.MathParser.VariableResolver
getset

VariableResolver delegate is used as a callback function that returns the values of variables when asked. This is useful when a variable cannot be defined before the parse operation. If VariableResolver property is set, it will be used to resolve variables that were not defined at the time parse operation has started. This means that syntax errors regarding undefined variables will not be caught at parse time. This VariableResolver (user implementation) will decide whether a variable name is valid or not. This is useful when for example the value comes from a database lookup. In some cases, the problem domain is too big to define the variables ahead of time. In such cases, it makes sense to parse with the assumption that it is a valid variable and resolve it's value when needed on demand during evaluation.

IConvertible Bestcode.MathParser.MathParser.X
getset

X property represents the X variable used in the mathematical expression which was input to be evaluated. You can set the X variable to a numeric or a string value and call the Parse method (or Value property) to retrieve the new result of the expression. X variable is created by default for the convenience of the user. Additional variables can be added by using the CreateVar method. Variable names are case insensitive. Throws Exception if variable X does not exist (was removed).

IConvertible Bestcode.MathParser.MathParser.Y
getset

Y property represents the Y variable used in the mathematical expression which was input to be evaluated. You can set the Y variable to a numeric or a string value and call the Parse method (or Value property) to retrieve the new result of the expression. Y variable is created by default for the convenience of the user. Additional variables can be added by using the CreateVar method. Variable names are case insensitive. Throws Exception if variable Y does not exist (was removed).