QgsExpressionFunction class

A abstract base class for defining QgsExpression functions.

Reference

Derived classes

class QgsArrayFilterExpressionFunction: Handles the array_filter(array, expression) expression function.
class QgsArrayForeachExpressionFunction: Handles the array_foreach(array, expression) expression function.
class QgsScopedExpressionFunction: Expression function for use within a QgsExpressionContextScope.
class QgsStaticExpressionFunction: c++ helper class for defining QgsExpression functions.
class QgsWithVariableExpressionFunction: Handles the with_variable(name, value, node) expression function.

Public types

class Parameter: Represents a single parameter passed to a function.
using FcnEval = QVariant(*)(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.
using ParameterList = QList<QgsExpressionFunction::Parameter>: List of parameters, used for function definition.

Constructors, destructors, conversion operators

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.
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.

Public functions

auto aliases() const -> QStringList virtual: Returns a list of possible aliases for the function.
auto func(const QVariantList& values, const QgsExpressionContext* context, QgsExpression* parent, const QgsExpressionNodeFunction* node) -> QVariant pure virtual: Returns result of evaluating the function.
auto group() const -> QString: Returns the first group which the function belongs to.
auto groups() const -> QStringList: Returns a list of the groups the function belongs to.
auto handlesNull() const -> bool virtual: Returns true if the function handles NULL values in arguments by itself, and the default NULL value handling should be skipped.
auto helpText() const -> const QString: The help text for the function.
auto isContextual() const -> bool: Returns whether the function is only available if provided by a QgsExpressionContext object.
auto isDeprecated() const -> bool virtual: Returns true if the function is deprecated and should not be presented as a valid option to users in expression builders.
auto isStatic(const QgsExpressionNodeFunction* node, QgsExpression* parent, const QgsExpressionContext* context) const -> bool virtual: Will be called during prepare to determine if the function is static.
auto lazyEval() const -> bool: True if this function should use lazy evaluation.
auto minParams() const -> int: The minimum number of parameters this function takes.
auto name() const -> QString: The name of the function.
auto parameters() const -> const QgsExpressionFunction::ParameterList&: Returns the list of named parameters for the function, if set.
auto params() const -> int: The number of parameters this function takes.
auto prepare(const QgsExpressionNodeFunction* node, QgsExpression* parent, const QgsExpressionContext* context) const -> bool virtual: This will be called during the prepare step() of an expression if it is not static.
auto referencedColumns(const QgsExpressionNodeFunction* node) const -> QSet<QString> virtual: Returns a set of field names which are required for this function.
auto run(QgsExpressionNode::NodeList* args, const QgsExpressionContext* context, QgsExpression* parent, const QgsExpressionNodeFunction* node) -> QVariant virtual: Evaluates the function, first evaluating all required arguments before passing them to the function's func() method.
auto usesGeometry(const QgsExpressionNodeFunction* node) const -> bool virtual: Does this function use a geometry object.

Protected static functions

static auto allParamsStatic(const QgsExpressionNodeFunction* node, QgsExpression* parent, const QgsExpressionContext* context) -> bool: 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.

Function documentation

QgsExpressionFunction::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.

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::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.

QStringList QgsExpressionFunction::aliases() const virtual

Returns a list of possible aliases for the function.

Returns	list of known aliases

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

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

QString QgsExpressionFunction::group() const

Returns the first group which the function belongs to.

QStringList QgsExpressionFunction::groups() const

Returns a list of the groups the function belongs to.

bool QgsExpressionFunction::isContextual() const

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

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.

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.

bool QgsExpressionFunction::lazyEval() const

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.

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

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

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.

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.

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

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.