Defines a function which can be used with the FunctionRegister. More...

#include <functiondefinition.h>

Inheritance diagram for FunctionDefinition:

Public Member Functions
	FunctionDefinition (const QString &category, const QString &name, unsigned argc=0, bool variadic=false)
	Construct a function definition. More...

	FunctionDefinition (const QString &category, const QString &name, const QString &description, unsigned argc=0, bool variadic=false)
	Construct a function definition. More...

virtual	~FunctionDefinition ()
	Virtual destructor.

const QString &	category () const
	Access the function categorisation for UI grouping. More...

void	setCategory (const QString &category)
	Set the category name for the function. More...

const QString &	name () const
	Access the function name as used by the expression generator. More...

void	setName (const QString &name)
	Set the function name as used by the generator. More...

const QString &	displayName () const
	Return the function name as displayed with the user. More...

void	setDisplayName (const QString &name)
	Set the function name as displayed to the user. More...

const QString &	description () const
	Access the function description. More...

void	setDesciption (const QString &description)
	Set the function description. More...

unsigned	argc () const
	Access the minimum argument count. More...

void	setArgc (unsigned count)
	Set the minimum required arguments. More...

bool	variadic () const
	Is the function variadic beyond `argc()`? More...

void	setVariadic (bool variadic)
	Set the variadic flag. More...

virtual void	evaluate (PlotFunctionResult &result, double time, unsigned int argc, const double argv, const PlotFunctionInfo &info, void context) const =0
	Evaluate the function with the given context data. More...

virtual void *	createContext () const
	Called to create an operating context for calculating function values. More...

virtual void	destroyContext (void *context) const
	Destroys the context created by `createContext()`. More...

QString	deduceDisplayName () const
	Deduces the display name of the function to show usage. More...

Detailed Description

Defines a function which can be used with the FunctionRegister.

The FunctionDefinition defines the name, category and parameters as well as supporting execution of the function given a particular set of values.

During expression evaluation, a PlotFunction manages binding the sub-expressions used to evaluate the arguments, evaluates those arguments and calls evaluate() with the results.

Before calling evalulate() the PlotFunction creates a context via createContext(). This represents context data used to track the valuation for a particular binding of the function. For example, this may contain a history of previous evaluations. The context is an arbitrary type and is released by calling destroyContext().

A function may also be variadic, requiring a minimum number of arguments, but supporting additional values. For example, the minof function supports any number of values, returning the minimum value.

Constructor & Destructor Documentation

FunctionDefinition::FunctionDefinition	(	const QString &	category,
		const QString &	name,
		unsigned	argc = `0`,
		bool	variadic = `false`
	)

Construct a function definition.

Parameters

category	The function's sorting category.
name	The function's evaluation name. The display name is deduced using `deduceDisplayName()`.
argc	The expected number of arguments. Exact if `variadic` is false, or a minimum otherwise.
variadic	Is the function variadic?

FunctionDefinition::FunctionDefinition	(	const QString &	category,
		const QString &	name,
		const QString &	description,
		unsigned	argc = `0`,
		bool	variadic = `false`
	)

Construct a function definition.

Parameters

category	The function's sorting category.
name	The function's evaluation name. The display name is deduced using `deduceDisplayName()`.
description	The function description.
argc	The expected number of arguments. Exact if `variadic` is false, or a minimum otherwise.
variadic	Is the function variadic?

Member Function Documentation

unsigned FunctionDefinition::argc ( ) const

inline

Access the minimum argument count.

Returns: The minimum number of arguments required.

const QString& FunctionDefinition::category ( ) const

inline

Access the function categorisation for UI grouping.

Returns: The function category name.

Referenced by setCategory().

virtual void* FunctionDefinition::createContext ( ) const

virtual

Called to create an operating context for calculating function values.

The context may be any type and represents working data required for the function. For example, this may hold a window of previous values for calculating a running average. The returned context is passed to evaluate().

The context is destroyed by destroyContext().

The default implementation returns null.

Returns: Working context data.

Reimplemented in FunctionMAvg.

QString FunctionDefinition::deduceDisplayName ( ) const

Deduces the display name of the function to show usage.

This takes the function name, adds brackets and a list of sequential parameter terms based on the number of expected parameters. Examples are below.

Name	`argc()`	`variadic()`	Result
abs	1	false	abs(x)
sqrt	1	false	abs(x)
abserr	2	false	abserr(x,y)
noargs	0	false	noargs()
onearg	1	false	onearg(x)
twoargs	2	false	twoargs(x,y)
threeargs	3	false	threeargs(x,y,z)
fourargs	4	false	fourargs(a,b,c,d)
maxofFunc	1	true	maxof(x...)

For three or less parameters, they are labelled x, y, z respectively. For more parameters, they are labelled a, b, c, ... to the required number of parameters. Finally, '...' is appended for variadic functions.

const QString& FunctionDefinition::description ( ) const

inline

Access the function description.

Returns: The function description.

Referenced by setDesciption().

virtual void FunctionDefinition::destroyContext ( void * context ) const

virtual

Destroys the context created by createContext().

The default implementation is empty.

Parameters

context The context created in createContext().

Reimplemented in FunctionMAvg.

const QString& FunctionDefinition::displayName ( ) const

inline

Return the function name as displayed with the user.

This better reflects how the function is used and should include parameter names and brackets for the parameter list.

See also: deduceDisplayName

Returns: The function name as displayed to the user.

virtual void FunctionDefinition::evaluate	(	PlotFunctionResult &	result,
		double	time,
		unsigned int	argc,
		const double *	argv,
		const PlotFunctionInfo &	info,
		void *	context
	)		const

pure virtual

Evaluate the function with the given context data.

This must look at the current state in info and evaluate results to result.

Parameters

[out]	result	The evaluation result is written here.
	time	The sample time being evaluated for.
	argc	The number of arguments actually given.
	argv	The list of calculated arguments, length `argc`. These are always logical values.
	info	Additional information about the current sampling.
	context	Additional context of the operation. May hold working data. This is optained via `createContext()`.

Implemented in FunctionSimple, FunctionClean, FunctionUnwrap, and FunctionMAvg.

const QString& FunctionDefinition::name ( ) const

inline

Access the function name as used by the expression generator.

Returns: The function name as used by the expression generator.

Referenced by setDisplayName(), and setName().

void FunctionDefinition::setArgc ( unsigned count )

inline

Set the minimum required arguments.

Parameters

count the Minimum argument count.

void FunctionDefinition::setCategory ( const QString & category )

inline

Set the category name for the function.

Parameters

category The new category name.

References category().

void FunctionDefinition::setDesciption ( const QString & description )

inline

Set the function description.

Parameters

description The new description.

References description().

void FunctionDefinition::setDisplayName ( const QString & name )

inline

Set the function name as displayed to the user.

Parameters

name	The new name.

References name().

void FunctionDefinition::setName ( const QString & name )

inline

Set the function name as used by the generator.

Parameters

name	The new name.

References name().

void FunctionDefinition::setVariadic ( bool variadic )

inline

Set the variadic flag.

Parameters

variadic True if the function can accept additional arguments.

References variadic().

bool FunctionDefinition::variadic ( ) const

inline

Is the function variadic beyond argc()?

Returns: True if the function can accept additional arguments.

Referenced by setVariadic().

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

functiondefinition.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation