QGIS API Documentation  3.37.0-Master (a5b4d9743e8)
Classes | Public Types | Public Member Functions | Static Protected Member Functions | List of all members
QgsExpressionFunction Class Referenceabstract

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

#include <qgsexpressionfunction.h>

Inheritance diagram for QgsExpressionFunction:
Inheritance graph
[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::ParameterParameterList
 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::ParameterListparameters () 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

List of parameters, used for function definition.

Definition at line 103 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 106 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.

Definition at line 126 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.

Definition at line 146 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.

Definition at line 166 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

Reimplemented in QgsStaticExpressionFunction.

Definition at line 129 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.

Definition at line 250 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
valueslist of values passed to the function
contextcontext expression is being evaluated against
parentparent expression
nodeexpression node
Returns
result of function

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

◆ 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 272 of file qgsexpressionfunction.h.

◆ groups()

QStringList QgsExpressionFunction::groups ( ) const
inline

Returns a list of the groups the function belongs to.

See also
group()

Definition at line 278 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 166 of file qgsexpressionfunction.cpp.

◆ helpText()

const QString QgsExpressionFunction::helpText ( ) const

The help text for the function.

Definition at line 85 of file qgsexpressionfunction.cpp.

◆ isContextual()

bool QgsExpressionFunction::isContextual ( ) const
inline

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

Definition at line 260 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.

Definition at line 156 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.

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

Definition at line 134 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 226 of file qgsexpressionfunction.h.

◆ minParams()

int QgsExpressionFunction::minParams ( ) const
inline

The minimum number of parameters this function takes.

Definition at line 192 of file qgsexpressionfunction.h.

◆ name()

QString QgsExpressionFunction::name ( ) const
inline

The name of the function.

Definition at line 186 of file qgsexpressionfunction.h.

◆ operator==()

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

Definition at line 161 of file qgsexpressionfunction.cpp.

◆ parameters()

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

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

Definition at line 209 of file qgsexpressionfunction.h.

◆ params()

int QgsExpressionFunction::params ( ) const
inline

The number of parameters this function takes.

Definition at line 189 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.

Reimplemented in QgsWithVariableExpressionFunction, QgsArrayFilterExpressionFunction, QgsArrayForeachExpressionFunction, and QgsStaticExpressionFunction.

Definition at line 142 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.

Reimplemented in QgsScopedExpressionFunction, and QgsStaticExpressionFunction.

Definition at line 150 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 QgsWithVariableExpressionFunction, QgsArrayFilterExpressionFunction, and QgsArrayForeachExpressionFunction.

Definition at line 90 of file qgsexpressionfunction.cpp.

◆ usesGeometry()

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

Does this function use a geometry object.

Reimplemented in QgsScopedExpressionFunction, and QgsStaticExpressionFunction.

Definition at line 123 of file qgsexpressionfunction.cpp.


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