QGIS API Documentation  3.1.0-Master (97726d6)
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, 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...
 
 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...
 
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 38 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 45 of file qgsexpressionfunction.h.

◆ ParameterList

List of parameters, used for function definition.

Definition at line 91 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 94 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 115 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 136 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 157 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 91 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 207 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 QgsWithVariableExpressionFunction, QgsStaticExpressionFunction, 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 270 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 277 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 128 of file qgsexpressionfunction.cpp.

◆ helpText()

const QString QgsExpressionFunction::helpText ( ) const

The help text for the function.

Definition at line 47 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 257 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 118 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 QgsWithVariableExpressionFunction, QgsStaticExpressionFunction, and QgsScopedExpressionFunction.

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

◆ minParams()

int QgsExpressionFunction::minParams ( ) const
inline

The minimum number of parameters this function takes.

Definition at line 183 of file qgsexpressionfunction.h.

◆ name()

QString QgsExpressionFunction::name ( ) const
inline

The name of the function.

Definition at line 177 of file qgsexpressionfunction.h.

◆ operator==()

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

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

◆ params()

int QgsExpressionFunction::params ( ) const
inline

The number of parameters this function takes.

Definition at line 180 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 QgsWithVariableExpressionFunction, and QgsStaticExpressionFunction.

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

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


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