A abstract base class for defining QgsExpression functions. More...

#include <qgsexpressionfunction.h>

Inheritance diagram for QgsExpressionFunction:

[legend]

Classes
class	Parameter
	Represents a single parameter passed to a function. More...

Public Types
typedef QVariant(*	FcnEval) (const QVariantList &values, const QgsExpressionContext context, QgsExpression parent, const QgsExpressionNodeFunction *node)
	Function definition for evaluation against an expression context, using a list of values as parameters to the function. More...

typedef QList< QgsExpressionFunction::Parameter >	ParameterList
	List of parameters, used for function definition. More...

Public Member Functions
	QgsExpressionFunction (const QString &fnname, const QgsExpressionFunction::ParameterList &params, const QString &group, const QString &helpText=QString(), bool lazyEval=false, bool handlesNull=false, bool isContextual=false)
	Constructor for function which uses named parameter list. More...

	QgsExpressionFunction (const QString &fnname, const QgsExpressionFunction::ParameterList &params, const QStringList &groups, const QString &helpText=QString(), bool lazyEval=false, bool handlesNull=false, bool isContextual=false)
	Constructor for function which uses named parameter list and group list. More...

	QgsExpressionFunction (const QString &fnname, int params, const QString &group, const QString &helpText=QString(), bool lazyEval=false, bool handlesNull=false, bool isContextual=false)
	Constructor for function which uses unnamed parameters. More...

	QgsExpressionFunction (const QString &fnname, int params, const QStringList &groups, const QString &helpText=QString(), bool lazyEval=false, bool handlesNull=false, bool isContextual=false)
	Constructor for function which uses unnamed parameters and group list. More...

virtual	~QgsExpressionFunction ()=default

virtual QStringList	aliases () const
	Returns a list of possible aliases for the function. More...

virtual QVariant	func (const QVariantList &values, const QgsExpressionContext context, QgsExpression parent, const QgsExpressionNodeFunction *node)=0
	Returns result of evaluating the function. More...

QString	group () const
	Returns the first group which the function belongs to. More...

QStringList	groups () const
	Returns a list of the groups the function belongs to. More...

virtual bool	handlesNull () const
	Returns `true` if the function handles NULL values in arguments by itself, and the default NULL value handling should be skipped. More...

const QString	helpText () const
	The help text for the function. More...

bool	isContextual () const
	Returns whether the function is only available if provided by a QgsExpressionContext object. More...

virtual bool	isDeprecated () const
	Returns `true` if the function is deprecated and should not be presented as a valid option to users in expression builders. More...

virtual bool	isStatic (const QgsExpressionNodeFunction node, QgsExpression parent, const QgsExpressionContext *context) const
	Will be called during prepare to determine if the function is static. More...

bool	lazyEval () const
	`true` if this function should use lazy evaluation. More...

int	minParams () const
	The minimum number of parameters this function takes. More...

QString	name () const
	The name of the function. More...

bool	operator== (const QgsExpressionFunction &other) const

const QgsExpressionFunction::ParameterList &	parameters () const
	Returns the list of named parameters for the function, if set. More...

int	params () const
	The number of parameters this function takes. More...

virtual bool	prepare (const QgsExpressionNodeFunction node, QgsExpression parent, const QgsExpressionContext *context) const
	This will be called during the prepare step() of an expression if it is not static. More...

virtual QSet< QString >	referencedColumns (const QgsExpressionNodeFunction *node) const
	Returns a set of field names which are required for this function. More...

virtual QVariant	run (QgsExpressionNode::NodeList args, const QgsExpressionContext context, QgsExpression parent, const QgsExpressionNodeFunction node)
	Evaluates the function, first evaluating all required arguments before passing them to the function's func() method. More...

virtual bool	usesGeometry (const QgsExpressionNodeFunction *node) const
	Does this function use a geometry object. More...

Static Protected Member Functions
static bool	allParamsStatic (const QgsExpressionNodeFunction node, QgsExpression parent, const QgsExpressionContext *context)
	This will return `true` if all the params for the provided function node are static within the constraints imposed by the context within the given parent. More...

Detailed Description

A abstract base class for defining QgsExpression functions.

Definition at line 40 of file qgsexpressionfunction.h.

Member Typedef Documentation

◆ FcnEval

typedef QVariant(* QgsExpressionFunction::FcnEval) (const QVariantList &values, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction *node)

Function definition for evaluation against an expression context, using a list of values as parameters to the function.

Definition at line 47 of file qgsexpressionfunction.h.

◆ ParameterList

typedef QList< QgsExpressionFunction::Parameter > QgsExpressionFunction::ParameterList

List of parameters, used for function definition.

Definition at line 104 of file qgsexpressionfunction.h.

Constructor & Destructor Documentation

◆ QgsExpressionFunction() [1/4]

QgsExpressionFunction::QgsExpressionFunction	(	const QString &	fnname,
		int	params,
		const QString &	group,
		const QString &	helpText = `QString()`,
		bool	lazyEval = `false`,
		bool	handlesNull = `false`,
		bool	isContextual = `false`
	)

inline

Constructor for function which uses unnamed parameters.

Definition at line 107 of file qgsexpressionfunction.h.

◆ QgsExpressionFunction() [2/4]

QgsExpressionFunction::QgsExpressionFunction	(	const QString &	fnname,
		int	params,
		const QStringList &	groups,
		const QString &	helpText = `QString()`,
		bool	lazyEval = `false`,
		bool	handlesNull = `false`,
		bool	isContextual = `false`
	)

inline

Constructor for function which uses unnamed parameters and group list.

Since: QGIS 3.0

Definition at line 128 of file qgsexpressionfunction.h.

◆ QgsExpressionFunction() [3/4]

QgsExpressionFunction::QgsExpressionFunction	(	const QString &	fnname,
		const QgsExpressionFunction::ParameterList &	params,
		const QString &	group,
		const QString &	helpText = `QString()`,
		bool	lazyEval = `false`,
		bool	handlesNull = `false`,
		bool	isContextual = `false`
	)

inline

Constructor for function which uses named parameter list.

Since: QGIS 2.16

Definition at line 149 of file qgsexpressionfunction.h.

◆ QgsExpressionFunction() [4/4]

QgsExpressionFunction::QgsExpressionFunction	(	const QString &	fnname,
		const QgsExpressionFunction::ParameterList &	params,
		const QStringList &	groups,
		const QString &	helpText = `QString()`,
		bool	lazyEval = `false`,
		bool	handlesNull = `false`,
		bool	isContextual = `false`
	)

inline

Constructor for function which uses named parameter list and group list.

Since: QGIS 3.0

Definition at line 170 of file qgsexpressionfunction.h.

◆ ~QgsExpressionFunction()

virtual QgsExpressionFunction::~QgsExpressionFunction ( )

virtualdefault

Member Function Documentation

◆ aliases()

QStringList QgsExpressionFunction::aliases ( ) const

virtual

Returns a list of possible aliases for the function.

These include other permissible names for the function, e.g., deprecated names.

Returns: list of known aliases

Since: QGIS 2.9

Reimplemented in QgsStaticExpressionFunction.

Definition at line 128 of file qgsexpressionfunction.cpp.

◆ allParamsStatic()

bool QgsExpressionFunction::allParamsStatic	(	const QgsExpressionNodeFunction *	node,
		QgsExpression *	parent,
		const QgsExpressionContext *	context
	)

staticprotected

This will return true if all the params for the provided function node are static within the constraints imposed by the context within the given parent.

This can be used as callback for custom implementations of subclasses. It is the default for implementation for StaticFunction::isStatic.

Since: QGIS 3.0

Definition at line 244 of file qgsexpressionfunction.cpp.

◆ func()

virtual QVariant QgsExpressionFunction::func	(	const QVariantList &	values,
		const QgsExpressionContext *	context,
		QgsExpression *	parent,
		const QgsExpressionNodeFunction *	node
	)

pure virtual

Returns result of evaluating the function.

Parameters

values	list of values passed to the function
context	context expression is being evaluated against
parent	parent expression
node	expression node

Returns: result of function

Implemented in QgsStaticExpressionFunction, QgsArrayForeachExpressionFunction, QgsArrayFilterExpressionFunction, QgsWithVariableExpressionFunction, and QgsScopedExpressionFunction.

◆ group()

QString QgsExpressionFunction::group ( ) const

inline

Returns the first group which the function belongs to.

Note: consider using groups() instead, as some functions naturally belong in multiple groups

Definition at line 283 of file qgsexpressionfunction.h.

◆ groups()

QStringList QgsExpressionFunction::groups ( ) const

inline

Returns a list of the groups the function belongs to.

See also: group()

Since: QGIS 3.0

Definition at line 290 of file qgsexpressionfunction.h.

◆ handlesNull()

bool QgsExpressionFunction::handlesNull ( ) const

virtual

Returns true if the function handles NULL values in arguments by itself, and the default NULL value handling should be skipped.

Definition at line 165 of file qgsexpressionfunction.cpp.

◆ helpText()

const QString QgsExpressionFunction::helpText ( ) const

The help text for the function.

Definition at line 84 of file qgsexpressionfunction.cpp.

◆ isContextual()

bool QgsExpressionFunction::isContextual ( ) const

inline

Returns whether the function is only available if provided by a QgsExpressionContext object.

Since: QGIS 2.12

Definition at line 270 of file qgsexpressionfunction.h.

◆ isDeprecated()

bool QgsExpressionFunction::isDeprecated ( ) const

virtual

Returns true if the function is deprecated and should not be presented as a valid option to users in expression builders.

Since: QGIS 3.0

Definition at line 155 of file qgsexpressionfunction.cpp.

◆ isStatic()

bool QgsExpressionFunction::isStatic	(	const QgsExpressionNodeFunction *	node,
		QgsExpression *	parent,
		const QgsExpressionContext *	context
	)		const

virtual

Will be called during prepare to determine if the function is static.

A function is static if it will return the same value for every feature with different attributes and/or geometry.

By default this will return true, if all arguments that have been passed to the function are also static.

Since: QGIS 3.0

Reimplemented in QgsStaticExpressionFunction, QgsArrayForeachExpressionFunction, QgsArrayFilterExpressionFunction, QgsWithVariableExpressionFunction, and QgsScopedExpressionFunction.

Definition at line 133 of file qgsexpressionfunction.cpp.

◆ lazyEval()

bool QgsExpressionFunction::lazyEval ( ) const

inline

true if this function should use lazy evaluation.

Lazy evaluation functions take QgsExpression::Node objects rather than the node results when called. You can use node->eval(parent, feature) to evaluate the node and return the result Functions are non lazy default and will be given the node return value when called.

Definition at line 232 of file qgsexpressionfunction.h.

◆ minParams()

int QgsExpressionFunction::minParams ( ) const

inline

The minimum number of parameters this function takes.

Definition at line 196 of file qgsexpressionfunction.h.

◆ name()

QString QgsExpressionFunction::name ( ) const

inline

The name of the function.

Definition at line 190 of file qgsexpressionfunction.h.

◆ operator==()

bool QgsExpressionFunction::operator== ( const QgsExpressionFunction & other ) const

Definition at line 160 of file qgsexpressionfunction.cpp.

◆ parameters()

const QgsExpressionFunction::ParameterList & QgsExpressionFunction::parameters ( ) const

inline

Returns the list of named parameters for the function, if set.

Since: QGIS 2.16

Definition at line 214 of file qgsexpressionfunction.h.

◆ params()

int QgsExpressionFunction::params ( ) const

inline

The number of parameters this function takes.

Definition at line 193 of file qgsexpressionfunction.h.

◆ prepare()

bool QgsExpressionFunction::prepare	(	const QgsExpressionNodeFunction *	node,
		QgsExpression *	parent,
		const QgsExpressionContext *	context
	)		const

virtual

This will be called during the prepare step() of an expression if it is not static.

This can be used by functions to do any preparation steps that might help to speedup the upcoming evaluation.

Since: QGIS 3.0

Reimplemented in QgsStaticExpressionFunction, QgsArrayForeachExpressionFunction, QgsArrayFilterExpressionFunction, and QgsWithVariableExpressionFunction.

Definition at line 141 of file qgsexpressionfunction.cpp.

◆ referencedColumns()

QSet< QString > QgsExpressionFunction::referencedColumns ( const QgsExpressionNodeFunction * node ) const

virtual

Returns a set of field names which are required for this function.

May contain QgsFeatureRequest::AllAttributes to signal that all attributes are required. If in doubt this will return more fields than strictly required.

Since: QGIS 3.0

Reimplemented in QgsStaticExpressionFunction, and QgsScopedExpressionFunction.

Definition at line 149 of file qgsexpressionfunction.cpp.

◆ run()

QVariant QgsExpressionFunction::run	(	QgsExpressionNode::NodeList *	args,
		const QgsExpressionContext *	context,
		QgsExpression *	parent,
		const QgsExpressionNodeFunction *	node
	)

virtual

Evaluates the function, first evaluating all required arguments before passing them to the function's func() method.

Reimplemented in QgsArrayForeachExpressionFunction, QgsArrayFilterExpressionFunction, and QgsWithVariableExpressionFunction.

Definition at line 89 of file qgsexpressionfunction.cpp.

◆ usesGeometry()

bool QgsExpressionFunction::usesGeometry ( const QgsExpressionNodeFunction * node ) const

virtual

Does this function use a geometry object.

Reimplemented in QgsStaticExpressionFunction, and QgsScopedExpressionFunction.

Definition at line 122 of file qgsexpressionfunction.cpp.

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

/build/qgis-3.28.0+99sid/src/core/expression/qgsexpressionfunction.h
/build/qgis-3.28.0+99sid/src/core/expression/qgsexpressionfunction.cpp

Classes

Public Types

Public Member Functions

Static Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ FcnEval

◆ ParameterList

Constructor & Destructor Documentation

◆ QgsExpressionFunction() [1/4]

◆ QgsExpressionFunction() [2/4]

◆ QgsExpressionFunction() [3/4]

◆ QgsExpressionFunction() [4/4]

◆ ~QgsExpressionFunction()

Member Function Documentation

◆ aliases()

◆ allParamsStatic()

◆ func()

◆ group()

◆ groups()

◆ handlesNull()

◆ helpText()

◆ isContextual()

◆ isDeprecated()

◆ isStatic()

◆ lazyEval()

◆ minParams()

◆ name()

◆ operator==()

◆ parameters()

◆ params()

◆ prepare()

◆ referencedColumns()

◆ run()

◆ usesGeometry()