c++ helper class for defining QgsExpression functions. More...

#include <qgsexpressionfunction.h>

Inheritance diagram for QgsStaticExpressionFunction:

Public Member Functions
	QgsStaticExpressionFunction (const QString &fnname, const QgsExpressionFunction::ParameterList &params, FcnEval fcn, const QString &group, const QString &helpText, const std::function< bool(const QgsExpressionNodeFunction node)> &usesGeometry, const std::function< QSet< QString >(const QgsExpressionNodeFunction node)> &referencedColumns, bool lazyEval=false, const QStringList &aliases=QStringList(), bool handlesNull=false)
	Static function for evaluation against a QgsExpressionContext, using a named list of parameter values.

	QgsStaticExpressionFunction (const QString &fnname, const QgsExpressionFunction::ParameterList &params, FcnEval fcn, const QString &group, const QString &helpText=QString(), bool usesGeometry=false, const QSet< QString > &referencedColumns=QSet< QString >(), bool lazyEval=false, const QStringList &aliases=QStringList(), bool handlesNull=false)
	Static function for evaluation against a QgsExpressionContext, using a named list of parameter values.

	QgsStaticExpressionFunction (const QString &fnname, const QgsExpressionFunction::ParameterList &params, FcnEval fcn, const QStringList &groups, const QString &helpText=QString(), bool usesGeometry=false, const QSet< QString > &referencedColumns=QSet< QString >(), bool lazyEval=false, const QStringList &aliases=QStringList(), bool handlesNull=false)
	Static function for evaluation against a QgsExpressionContext, using a named list of parameter values and list of groups.

	QgsStaticExpressionFunction (const QString &fnname, int params, FcnEval fcn, const QString &group, const QString &helpText=QString(), bool usesGeometry=false, const QSet< QString > &referencedColumns=QSet< QString >(), bool lazyEval=false, const QStringList &aliases=QStringList(), bool handlesNull=false)
	Static function for evaluation against a QgsExpressionContext, using an unnamed list of parameter values.

	QgsStaticExpressionFunction (const QString &fnname, int params, FcnEval fcn, const QStringList &groups, const QString &helpText=QString(), bool usesGeometry=false, const QSet< QString > &referencedColumns=QSet< QString >(), bool lazyEval=false, const QStringList &aliases=QStringList(), bool handlesNull=false)
	Static function for evaluation against a QgsExpressionContext, using an unnamed list of parameter values and list of groups.

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

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

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

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

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

void	setIsStatic (bool isStatic)
	Tag this function as either static or not static.

void	setIsStaticFunction (const std::function< bool(const QgsExpressionNodeFunction , QgsExpression , const QgsExpressionContext *) > &isStatic)
	Set a function that will be called in the prepare step to determine if the function is static or not.

void	setPrepareFunction (const std::function< bool(const QgsExpressionNodeFunction , QgsExpression , const QgsExpressionContext *)> &prepareFunc)
	Set a function that will be called in the prepare step to determine if the function is static or not.

void	setUsesGeometryFunction (const std::function< bool(const QgsExpressionNodeFunction *node)> &usesGeometry)
	Set a function that will be called when determining if the function requires feature geometry or not.

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

Public Member Functions inherited from 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)
	Constructor for function which uses named parameter list.

	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.

	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.

	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.

virtual	~QgsExpressionFunction ()=default

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

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

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.

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

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

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.

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

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

QString	name () const
	The name of the function.

bool	operator== (const QgsExpressionFunction &other) const

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

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

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.

Static Public Member Functions
static const QList< QgsExpressionFunction * > &	functions ()
	Returns a list of all registered expression functions.

Additional Inherited Members
Public Types inherited from QgsExpressionFunction
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.

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

Static Protected Member Functions inherited from QgsExpressionFunction
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.

Detailed Description

c++ helper class for defining QgsExpression functions.

Note: not available in Python bindings

Definition at line 336 of file qgsexpressionfunction.h.

Constructor & Destructor Documentation

◆ QgsStaticExpressionFunction() [1/5]

QgsStaticExpressionFunction::QgsStaticExpressionFunction	(	const QString &	fnname,
		int	params,
		FcnEval	fcn,
		const QString &	group,
		const QString &	helpText = `QString()`,
		bool	usesGeometry = `false`,
		const QSet< QString > &	referencedColumns = `QSet<QString>()`,
		bool	lazyEval = `false`,
		const QStringList &	aliases = `QStringList()`,
		bool	handlesNull = `false`
	)

inline

Static function for evaluation against a QgsExpressionContext, using an unnamed list of parameter values.

Definition at line 343 of file qgsexpressionfunction.h.

◆ QgsStaticExpressionFunction() [2/5]

QgsStaticExpressionFunction::QgsStaticExpressionFunction	(	const QString &	fnname,
		int	params,
		FcnEval	fcn,
		const QStringList &	groups,
		const QString &	helpText = `QString()`,
		bool	usesGeometry = `false`,
		const QSet< QString > &	referencedColumns = `QSet<QString>()`,
		bool	lazyEval = `false`,
		const QStringList &	aliases = `QStringList()`,
		bool	handlesNull = `false`
	)

inline

Static function for evaluation against a QgsExpressionContext, using an unnamed list of parameter values and list of groups.

Definition at line 365 of file qgsexpressionfunction.h.

◆ QgsStaticExpressionFunction() [3/5]

QgsStaticExpressionFunction::QgsStaticExpressionFunction	(	const QString &	fnname,
		const QgsExpressionFunction::ParameterList &	params,
		FcnEval	fcn,
		const QString &	group,
		const QString &	helpText = `QString()`,
		bool	usesGeometry = `false`,
		const QSet< QString > &	referencedColumns = `QSet<QString>()`,
		bool	lazyEval = `false`,
		const QStringList &	aliases = `QStringList()`,
		bool	handlesNull = `false`
	)

inline

Static function for evaluation against a QgsExpressionContext, using a named list of parameter values.

Definition at line 386 of file qgsexpressionfunction.h.

◆ QgsStaticExpressionFunction() [4/5]

QgsStaticExpressionFunction::QgsStaticExpressionFunction	(	const QString &	fnname,
		const QgsExpressionFunction::ParameterList &	params,
		FcnEval	fcn,
		const QString &	group,
		const QString &	helpText,
		const std::function< bool(const QgsExpressionNodeFunction *node)> &	usesGeometry,
		const std::function< QSet< QString >(const QgsExpressionNodeFunction *node)> &	referencedColumns,
		bool	lazyEval = `false`,
		const QStringList &	aliases = `QStringList()`,
		bool	handlesNull = `false`
	)

Static function for evaluation against a QgsExpressionContext, using a named list of parameter values.

Lambda functions can be provided that will be called to determine if a geometry is used an which columns are referenced. This is only required if this cannot be determined by calling each parameter node's usesGeometry() or referencedColumns() method. For example, an aggregate expression requires the geometry and all columns if the parent variable is used. If nullptr is passed as a node to these functions, they should stay on the safe side and return if they could potentially require a geometry or columns.

◆ QgsStaticExpressionFunction() [5/5]

QgsStaticExpressionFunction::QgsStaticExpressionFunction	(	const QString &	fnname,
		const QgsExpressionFunction::ParameterList &	params,
		FcnEval	fcn,
		const QStringList &	groups,
		const QString &	helpText = `QString()`,
		bool	usesGeometry = `false`,
		const QSet< QString > &	referencedColumns = `QSet<QString>()`,
		bool	lazyEval = `false`,
		const QStringList &	aliases = `QStringList()`,
		bool	handlesNull = `false`
	)

inline

Static function for evaluation against a QgsExpressionContext, using a named list of parameter values and list of groups.

Definition at line 429 of file qgsexpressionfunction.h.

Member Function Documentation

◆ aliases()

QStringList QgsStaticExpressionFunction::aliases ( ) const

overridevirtual

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

Reimplemented from QgsExpressionFunction.

Definition at line 192 of file qgsexpressionfunction.cpp.

◆ func()

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

inlineoverridevirtual

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	function node

Returns: result of function

Implements QgsExpressionFunction.

Definition at line 454 of file qgsexpressionfunction.h.

◆ functions()

static const QList< QgsExpressionFunction * > & QgsStaticExpressionFunction::functions ( )

static

Returns a list of all registered expression functions.

◆ isStatic()

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

overridevirtual

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.

Reimplemented from QgsExpressionFunction.

Definition at line 218 of file qgsexpressionfunction.cpp.

◆ prepare()

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

overridevirtual

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.

Reimplemented from QgsExpressionFunction.

Definition at line 226 of file qgsexpressionfunction.cpp.

◆ referencedColumns()

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

overridevirtual

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.

Reimplemented from QgsExpressionFunction.

Definition at line 210 of file qgsexpressionfunction.cpp.

◆ setIsStatic()

void QgsStaticExpressionFunction::setIsStatic ( bool isStatic )

Tag this function as either static or not static.

This will indicate that the function is always expected to return the same value for an iteration (or explicitly request that it's going to be called for every feature, if false).

See also: setIsStaticFunction

Definition at line 239 of file qgsexpressionfunction.cpp.

◆ setIsStaticFunction()

void QgsStaticExpressionFunction::setIsStaticFunction ( const std::function< bool(const QgsExpressionNodeFunction *, QgsExpression *, const QgsExpressionContext *) > & isStatic )

Set a function that will be called in the prepare step to determine if the function is static or not.

By default this is set to a function that checks all arguments that have been passed to the variable and if all of them are static, it will be assumed that the function is static as well.

Definition at line 234 of file qgsexpressionfunction.cpp.

◆ setPrepareFunction()

void QgsStaticExpressionFunction::setPrepareFunction ( const std::function< bool(const QgsExpressionNodeFunction *, QgsExpression *, const QgsExpressionContext *)> & prepareFunc )

Set a function that will be called in the prepare step to determine if the function is static or not.

By default this is set to a function that checks all arguments that have been passed to the variable and if all of them are static, it will be assumed that the function is static as well.

Definition at line 245 of file qgsexpressionfunction.cpp.

◆ setUsesGeometryFunction()

void QgsStaticExpressionFunction::setUsesGeometryFunction ( const std::function< bool(const QgsExpressionNodeFunction *node)> & usesGeometry )

Set a function that will be called when determining if the function requires feature geometry or not.

Since: QGIS 3.30

Definition at line 205 of file qgsexpressionfunction.cpp.

◆ usesGeometry()

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

overridevirtual

Does this function use a geometry object.

Reimplemented from QgsExpressionFunction.

Definition at line 197 of file qgsexpressionfunction.cpp.

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

/build/qgis-3.41.0+git20241122+3440c17df1d+99sid/src/core/expression/qgsexpressionfunction.h
/build/qgis-3.41.0+git20241122+3440c17df1d+99sid/src/core/expression/qgsexpressionfunction.cpp

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ QgsStaticExpressionFunction() [1/5]

◆ QgsStaticExpressionFunction() [2/5]

◆ QgsStaticExpressionFunction() [3/5]

◆ QgsStaticExpressionFunction() [4/5]

◆ QgsStaticExpressionFunction() [5/5]

Member Function Documentation

◆ aliases()

◆ func()

◆ functions()

◆ isStatic()

◆ prepare()

◆ referencedColumns()

◆ setIsStatic()

◆ setIsStaticFunction()

◆ setPrepareFunction()

◆ setUsesGeometryFunction()

◆ usesGeometry()