#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 FormulaParserInterface *	Alloc (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()

static MAXON_METHOD FormulaParserInterface* Alloc ( MAXON_SOURCE_LOCATION_DECLARATION )

static

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]	name	Name of the variable.
[in]	val	Pointer to the variable. Note that the pointer must always be valid when Calculate or Evaluate are called.
[in]	caseSensitive	If 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]	name	Name of the variable.
[in]	val	Pointer to the variable. Note that the pointer must always be valid when Calculate or Evaluate are called.
[in]	caseSensitive	If 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]	name	Name of the variable.
[in]	val	Pointer to the variable. Note that the pointer must always be valid when Calculate or Evaluate are called.
[in]	caseSensitive	If 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]	name	Name of the variable.
[in]	caseSensitive	If 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]	cache	Cache that will be created.
[in]	formula	Formula to be parsed.
[in]	unit	The 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]	angleUnit	The angular unit that trigonometric functions expect as input / produce as output.
[in]	base	The 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]	integerMode	Calculate 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]	cache	Pre-parsed cache generated by CalculateParserCache.
[out]	result	Will 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]	cache	Pre-parsed cache generated by CalculateParserCache.
[out]	result	Will 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]	formula	Formula to be parsed.
[out]	result	Will be filled with the result of the formula (might even be the case if a neglectable error occured) or 0.0.
[in]	unit	The 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]	angleUnit	The angular unit that trigonometric functions expect as input / produce as output.
[in]	base	The 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]	formula	Formula to be parsed.
[out]	result	Will be filled with the result of the formula (might even be the case if a neglectable error occured) or 0.
[in]	unit	The 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]	angleUnit	The angular unit that trigonometric functions expect as input / produce as output.
[in]	base	The 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]	name	Name of the variable.
[in]	val	Pointer to the variable. Note that the pointer must always be valid when Calculate or Evaluate are called.
[in]	caseSensitive	If 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]	name	Name of the variable.
[in]	caseSensitive	If 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]	name	Name of the variable.
[in]	caseSensitive	If 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]	name	Name of the variable.
[in]	caseSensitive	If 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]	name	Name of the variable.
[in]	caseSensitive	If 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]	cache	Pre-parsed cache generated by CalculateParserCache. Cache is const and can be used in multi threaded execution.
[in]	varOverrides	Variable dictionary that can be supplied as an override for multi threaded execution.
[out]	result	Will 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]	cache	Pre-parsed cache generated by CalculateParserCache. The cache might be modified during this call.
[out]	result	Will 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]	cache	Pre-parsed cache generated by CalculateParserCache. The cache will not be modified during this call.
[in]	resultVariableName	The variable name where the result should be stored.
[out]	result	Will be filled with the shader code of the formula.

Returns: OK on success.

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Member Typedef Documentation

◆ VariableDictionary

Member Function Documentation

◆ MAXON_INTERFACE_NONVIRTUAL()

◆ Alloc()

◆ AddFloatVariable()

◆ AddIntVariable()

◆ AddStringVariable()

◆ RemoveVariable()

◆ CalculateParserCache()

◆ CalculateFloat() [1/4]

◆ CalculateFloat() [2/4]

◆ CalculateInt() [1/2]

◆ EvaluateFloat()

◆ EvaluateInt()

◆ AddDataVariable()

◆ AddDummyFloatVariable()

◆ AddDummyIntVariable()

◆ AddDummyStringVariable()

◆ AddDummyDataVariable()

◆ CalculateFloat() [3/4]

◆ CalculateFloat() [4/4]

◆ CalculateInt() [2/2]

◆ GenerateShaderCode()