FormulaParserInterface Class Reference

#include <formulaparser.h>

Detailed Description

Calculates the result of mathematical expressions provided as strings.

The parser supports the unit types km, m, cm, mm, um (also micron-sign-character + m), nm, mi, yd, ft, and in. It also supports the functions sin(x), cos(x), acos(x), asin(x), tan(x), atan(x), cosh(x), sinh(x), tanh(x), floor(x), ceil(x), round(x), abs(x), sqr(x), sqrt(x), exp(x), log(x), log10(x), trunc(x), rnd(x) (random value between 0 and x), rnd(x;y) (y is a seed value), pow(x;y), mod(a;b), clamp(x;lower;upper), min(x;y), max(x;y), a&lt&ltb, (x)shl(y) (bitwise shift), a>>b, (x)shr(y) (bitwise shift), and len(a;b;...) (vector length of two or more components). Addtionally, the operators +, -, *, /, (, ), =, ==, >, >=, <, <=, !=, ! (bitwise not), ||, or, &&, and, & (bitwise and), | (bitwise or), ^ (bitwise xor), ~ (bitwise not), cond?(x;y) (conditional statement), and if (cond;x;y) (conditional statement) are supported. The symbols e and pi are being interpreted as the respective irrational numbers, and both the dot and comma character will be interpreted as a decimal point.

The interface can throw the errors FormulaExecutionError, FormulaNumberError, and FormulaParseError.

Public Types

using VariableDictionary = DataDictionary
 

Public Member Functions

MAXON_METHOD Result< void > AddFloatVariable (const String &name, Float64 *val, Bool caseSensitive)
 
MAXON_METHOD Result< void > AddIntVariable (const String &name, Int64 *val, Bool caseSensitive)
 
MAXON_METHOD Result< void > AddStringVariable (const String &name, String *val, Bool caseSensitive)
 
MAXON_METHOD Result< void > RemoveVariable (const String &name, Bool caseSensitive)
 
MAXON_METHOD Result< void > CalculateParserCache (FormulaParserCacheRef &cache, const String &formula, METRICUNIT unit, ANGLEUNIT angleUnit, Int base, Bool integerMode)
 
MAXON_METHOD Result< void > CalculateFloat (FormulaParserCacheRef &cache, Float32 &result)
 
MAXON_METHOD Result< void > CalculateFloat (FormulaParserCacheRef &cache, Float64 &result)
 
MAXON_METHOD Result< void > CalculateInt (FormulaParserCacheRef &cache, Int64 &result)
 
MAXON_METHOD Result< void > EvaluateFloat (const String &formula, Float64 &result, METRICUNIT unit=METRICUNIT::NONE, ANGLEUNIT angleUnit=ANGLEUNIT::RADIANS, Int base=10)
 
MAXON_METHOD Result< void > EvaluateInt (const String &formula, Int64 &result, METRICUNIT unit=METRICUNIT::NONE, ANGLEUNIT angleUnit=ANGLEUNIT::RADIANS, Int base=10)
 
MAXON_METHOD Result< void > AddDataVariable (const String &name, Data *val, Bool caseSensitive)
 
MAXON_METHOD Result< void > AddDummyFloatVariable (const String &name, Bool caseSensitive)
 
MAXON_METHOD Result< void > AddDummyIntVariable (const String &name, Bool caseSensitive)
 
MAXON_METHOD Result< void > AddDummyStringVariable (const String &name, Bool caseSensitive)
 
MAXON_METHOD Result< void > AddDummyDataVariable (const String &name, Bool caseSensitive)
 
MAXON_METHOD Result< void > CalculateFloat (const FormulaParserCacheRef &cache, const VariableDictionary &varOverrides, Float32 &result)
 
MAXON_METHOD Result< void > CalculateFloat (const FormulaParserCacheRef &cache, const VariableDictionary &varOverrides, Float64 &result)
 
MAXON_METHOD Result< void > CalculateInt (const FormulaParserCacheRef &cache, const VariableDictionary &varOverrides, Int64 &result)
 
MAXON_METHOD Result< void > GenerateShaderCode (const FormulaParserCacheRef &cache, const String &resultVariableName, String &result)
 

Static Public Member Functions

static MAXON_METHOD FormulaParserInterfaceAlloc (MAXON_SOURCE_LOCATION_DECLARATION)
 

Private Member Functions

 MAXON_INTERFACE_NONVIRTUAL (FormulaParserInterface, MAXON_REFERENCE_NORMAL, "net.maxon.interface.formulaparser")
 

Member Typedef Documentation

◆ VariableDictionary

using VariableDictionary = DataDictionary

Member Function Documentation

◆ MAXON_INTERFACE_NONVIRTUAL()

MAXON_INTERFACE_NONVIRTUAL ( FormulaParserInterface  ,
MAXON_REFERENCE_NORMAL  ,
"net.maxon.interface.formulaparser"   
)
private

◆ Alloc()

allocator for common use.

◆ AddFloatVariable()

MAXON_METHOD Result<void> AddFloatVariable ( const String name,
Float64 val,
Bool  caseSensitive 
)

Adds a floating point variable to the formula parser. All variables must be known to the parser for CalculateParserCache calls.

Parameters
[in]nameName of the variable.
[in]valPointer to the variable. Note that the pointer must always be valid when Calculate or Evaluate are called.
[in]caseSensitiveIf false, then the user can write the letters of the variable using any lower/uppercase combinations.
Returns
OK on success. IllegalArgumentError is returned if a variable was already present.

◆ AddIntVariable()

MAXON_METHOD Result<void> AddIntVariable ( const String name,
Int64 val,
Bool  caseSensitive 
)

Adds an integer variable to the formula parser. All variables must be known to the parser for CalculateParserCache calls.

Parameters
[in]nameName of the variable.
[in]valPointer to the variable. Note that the pointer must always be valid when Calculate or Evaluate are called.
[in]caseSensitiveIf false, then the user can write the letters of the variable using any lower/uppercase combinations.
Returns
OK on success. IllegalArgumentError is returned if a variable was already present.

◆ AddStringVariable()

MAXON_METHOD Result<void> AddStringVariable ( const String name,
String val,
Bool  caseSensitive 
)

Adds a string variable to the formula parser. All variables must be known to the parser for CalculateParserCache calls.

Parameters
[in]nameName of the variable.
[in]valPointer to the variable. Note that the pointer must always be valid when Calculate or Evaluate are called.
[in]caseSensitiveIf false, then the user can write the letters of the variable using any lower/uppercase combinations.
Returns
OK on success. IllegalArgumentError is returned if a variable was already present.

◆ RemoveVariable()

MAXON_METHOD Result<void> RemoveVariable ( const String name,
Bool  caseSensitive 
)

Removes variable from the formula parser.

Parameters
[in]nameName of the variable.
[in]caseSensitiveIf false, then any variable that matches any possible lower/uppercase combination will be picked.
Returns
OK on success. IllegalArgumentError is returned if a variable was not present.

◆ CalculateParserCache()

MAXON_METHOD Result<void> CalculateParserCache ( FormulaParserCacheRef &  cache,
const String formula,
METRICUNIT  unit,
ANGLEUNIT  angleUnit,
Int  base,
Bool  integerMode 
)

Translates a formula expression string into a pre-parsed cache.

Parameters
[out]cacheCache that will be created.
[in]formulaFormula to be parsed.
[in]unitThe metric unit format for the result value. If set to METRICUNIT::NONE all metric units will be ignored as if they were not present.
[in]angleUnitThe angular unit that trigonometric functions expect as input / produce as output.
[in]baseThe numerical base for numbers in the range of [2..36], by default 10. If the base is != 10 then any number will be parsed as an integer value.
[in]integerModeCalculate expressions with integer numbers (floating point values cannot accurately represent most of the Int64 values)
Returns
OK on success.

◆ CalculateFloat() [1/4]

MAXON_METHOD Result<void> CalculateFloat ( FormulaParserCacheRef &  cache,
Float32 result 
)

Executes a floating point formula calculation using a pre-parsed cache for better performance. This method is not thread safe. See the const version of CalculateFloat/Int for thread safe calls.

Parameters
[in]cachePre-parsed cache generated by CalculateParserCache.
[out]resultWill be filled with the result of the formula (even if a neglectable error occurred) or 0.0.
Returns
OK on success.

◆ CalculateFloat() [2/4]

MAXON_METHOD Result<void> CalculateFloat ( FormulaParserCacheRef &  cache,
Float64 result 
)

◆ CalculateInt() [1/2]

MAXON_METHOD Result<void> CalculateInt ( FormulaParserCacheRef &  cache,
Int64 result 
)

Executes an integer formula calculation using a pre-parsed cache for better performance. This method is not thread safe. See the const version of CalculateFloat/Int for thread safe calls.

Parameters
[in]cachePre-parsed cache generated by CalculateParserCache.
[out]resultWill be filled with the result of the formula (even if a neglectable error occurred) or 0.
Returns
OK on success.

◆ EvaluateFloat()

MAXON_METHOD Result<void> EvaluateFloat ( const String formula,
Float64 result,
METRICUNIT  unit = METRICUNIT::NONE,
ANGLEUNIT  angleUnit = ANGLEUNIT::RADIANS,
Int  base = 10 
)

Evaluates a floating point formula. If you need multiple calls to the same formula (e.g. when variables are used) use CalculateParserCache and CalculateFloat for better performance. This method is not thread safe. See the const version of CalculateFloat/Int for thread safe calls.

Parameters
[in]formulaFormula to be parsed.
[out]resultWill be filled with the result of the formula (might even be the case if a neglectable error occured) or 0.0.
[in]unitThe metric unit format for the result value. If set to METRICUNIT::NONE all metric units will be ignored as if they were not present.
[in]angleUnitThe angular unit that trigonometric functions expect as input / produce as output.
[in]baseThe numerical base for numbers in the range of [2..36], by default 10. If the base is != 10 then any number will be parsed as an integer value.
Returns
OK on success.

◆ EvaluateInt()

MAXON_METHOD Result<void> EvaluateInt ( const String formula,
Int64 result,
METRICUNIT  unit = METRICUNIT::NONE,
ANGLEUNIT  angleUnit = ANGLEUNIT::RADIANS,
Int  base = 10 
)

Evaluates an integer formula. If you need multiple calls to the same formula (e.g. when variables are used) use CalculateParserCache and CalculateInt for better performance. This method is not thread safe. See the const version of CalculateFloat/Int for thread safe calls.

Parameters
[in]formulaFormula to be parsed.
[out]resultWill be filled with the result of the formula (might even be the case if a neglectable error occured) or 0.
[in]unitThe metric unit format for the result value. If set to METRICUNIT::NONE all metric units will be ignored as if they were not present.
[in]angleUnitThe angular unit that trigonometric functions expect as input / produce as output.
[in]baseThe numerical base for numbers in the range of [2..36], by default 10.
Returns
OK on success.

◆ AddDataVariable()

MAXON_METHOD Result<void> AddDataVariable ( const String name,
Data val,
Bool  caseSensitive 
)

Adds a Data variable to the formula parser. All variables must be known to the parser for CalculateParserCache calls.

Parameters
[in]nameName of the variable.
[in]valPointer to the variable. Note that the pointer must always be valid when Calculate or Evaluate are called.
[in]caseSensitiveIf false, then the user can write the letters of the variable using any lower/uppercase combinations.
Returns
OK on success. IllegalArgumentError is returned if a variable was already present.

◆ AddDummyFloatVariable()

MAXON_METHOD Result<void> AddDummyFloatVariable ( const String name,
Bool  caseSensitive 
)

Adds a floating point variable to the formula parser with no valid address. Parser will only refer to the name for formula caching. All variables must be known to the parser for CalculateParserCache calls, even if they are dummies.

Parameters
[in]nameName of the variable.
[in]caseSensitiveIf false, then the user can write the letters of the variable using any lower/uppercase combinations.
Returns
OK on success. IllegalArgumentError is returned if a variable was already present.

◆ AddDummyIntVariable()

MAXON_METHOD Result<void> AddDummyIntVariable ( const String name,
Bool  caseSensitive 
)

Adds an integer variable to the formula parser with no valid address. Parser will only refer to the name for formula caching. All variables must be known to the parser for CalculateParserCache calls, even if they are dummies.

Parameters
[in]nameName of the variable.
[in]caseSensitiveIf false, then the user can write the letters of the variable using any lower/uppercase combinations.
Returns
OK on success. IllegalArgumentError is returned if a variable was already present.

◆ AddDummyStringVariable()

MAXON_METHOD Result<void> AddDummyStringVariable ( const String name,
Bool  caseSensitive 
)

Adds a string variable to the formula parser with no valid address. Parser will only refer to the name for formula caching. All variables must be known to the parser for CalculateParserCache calls, even if they are dummies.

Parameters
[in]nameName of the variable.
[in]caseSensitiveIf false, then the user can write the letters of the variable using any lower/uppercase combinations.
Returns
OK on success. IllegalArgumentError is returned if a variable was already present.

◆ AddDummyDataVariable()

MAXON_METHOD Result<void> AddDummyDataVariable ( const String name,
Bool  caseSensitive 
)

Adds a Data variable to the formula parser with no valid address. Parser will only refer to the name for formula caching. All variables must be known to the parser for CalculateParserCache calls, even if they are dummies.

Parameters
[in]nameName of the variable.
[in]caseSensitiveIf false, then the user can write the letters of the variable using any lower/uppercase combinations.
Returns
OK on success. IllegalArgumentError is returned if a variable was already present.

◆ CalculateFloat() [3/4]

MAXON_METHOD Result<void> CalculateFloat ( const FormulaParserCacheRef &  cache,
const VariableDictionary varOverrides,
Float32 result 
)

Executes a floating point formula calculation using a pre-parsed cache for better performance. Method is thread safe if used with the #varOverrides dictionary. Each thread must supply it's own variable's address so the parser can be given a specific variable value on each thread. I.e. use with AddDummyXVariable methods. The variable names must match those given through the AddFloat/Int/StringVariable calls. If #caseSensitive was false, the VariableDictionary key should be an upper case hashed string.

Parameters
[in]cachePre-parsed cache generated by CalculateParserCache. Cache is const and can be used in multi threaded execution.
[in]varOverridesVariable dictionary that can be supplied as an override for multi threaded execution.
[out]resultWill be filled with the result of the formula (even if a neglectable error occurred) or 0.0.
Returns
OK on success.

◆ CalculateFloat() [4/4]

MAXON_METHOD Result<void> CalculateFloat ( const FormulaParserCacheRef &  cache,
const VariableDictionary varOverrides,
Float64 result 
)

◆ CalculateInt() [2/2]

MAXON_METHOD Result<void> CalculateInt ( const FormulaParserCacheRef &  cache,
const VariableDictionary varOverrides,
Int64 result 
)

Executes an integer formula calculation using a pre-parsed cache for better performance. Method is thread safe if used with the #varOverrides dictionary. Each thread must supply it's own variable's address so the parser can be given a specific variable value on each thread. I.e. use with AddDummyXVariable methods. The variable names must match those given through the AddFloat/Int/StringVariable calls. If #caseSensitive was false, the VariableDictionary key should be an upper case hashed string.

Parameters
[in,out]cachePre-parsed cache generated by CalculateParserCache. The cache might be modified during this call.
[out]resultWill be filled with the result of the formula (even if a neglect able error occurred) or 0.
Returns
OK on success.

◆ GenerateShaderCode()

MAXON_METHOD Result<void> GenerateShaderCode ( const FormulaParserCacheRef &  cache,
const String resultVariableName,
String result 
)

Converts the formula into simple c-like shader code. This supports 32bit float only.

Parameters
[in]cachePre-parsed cache generated by CalculateParserCache. The cache will not be modified during this call.
[in]resultVariableNameThe variable name where the result should be stored.
[out]resultWill be filled with the shader code of the formula.
Returns
OK on success.