QgsStaticExpressionFunction class

c++ helper class for defining QgsExpression functions.

Reference

Base classes

class QgsExpressionFunction: A abstract base class for defining QgsExpression functions.

Public static functions

static auto functions() -> const QList<QgsExpressionFunction*>&: Returns a list of all registered expression functions.

Constructors, destructors, conversion operators

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

Public functions

auto aliases() const -> QStringList override: Returns a list of possible aliases for the function.
auto func(const QVariantList& values, const QgsExpressionContext* context, QgsExpression* parent, const QgsExpressionNodeFunction* node) -> QVariant override: Returns result of evaluating the function.
auto isStatic(const QgsExpressionNodeFunction* node, QgsExpression* parent, const QgsExpressionContext* context) const -> bool override: Will be called during prepare to determine if the function is static.
auto prepare(const QgsExpressionNodeFunction* node, QgsExpression* parent, const QgsExpressionContext* context) const -> bool override: This will be called during the prepare step() of an expression if it is not static.
auto referencedColumns(const QgsExpressionNodeFunction* node) const -> QSet<QString> 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.
auto usesGeometry(const QgsExpressionNodeFunction* node) const -> bool override: Does this function use a geometry object.

Function documentation

QgsStaticExpressionFunction::QgsStaticExpressionFunction(const QString& fnname, const QgsExpressionFunction::ParameterList& params, FcnEval fcn, const QString& group, const QString& helpText, const std::function<bool(const QgsExpressionNodeFunctionnode)>& usesGeometry, const std::function<QSet<QString>(const QgsExpressionNodeFunctionnode)>& 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 a 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.

QStringList QgsStaticExpressionFunction::aliases() const override

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 QgsStaticExpressionFunction::func(const QVariantList& values, const QgsExpressionContext* context, QgsExpression* parent, const QgsExpressionNodeFunction* node) override

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

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

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

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

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

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.

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

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.

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