QGIS API Documentation  3.23.0-Master (dd0cd13a00)
Classes | Public Types | Public Member Functions | Public Attributes | Protected Member Functions | Protected Attributes | List of all members
QgsExpressionNode Class Referenceabstract

Abstract base class for all nodes that can appear in an expression. More...

#include <qgsexpressionnode.h>

Inheritance diagram for QgsExpressionNode:
Inheritance graph
[legend]

Classes

struct  NamedNode
 Named node. More...
 
class  NodeList
 A list of expression nodes. More...
 

Public Types

enum  NodeType {
  ntUnaryOperator , ntBinaryOperator , ntInOperator , ntFunction ,
  ntLiteral , ntColumnRef , ntCondition , ntIndexOperator
}
 Known node types. More...
 

Public Member Functions

virtual ~QgsExpressionNode ()=default
 
QVariant cachedStaticValue () const
 Returns the node's static cached value. More...
 
virtual QgsExpressionNodeclone () const =0
 Generate a clone of this node. More...
 
virtual QString dump () const =0
 Dump this node into a serialized (part) of an expression. More...
 
const QgsExpressionNodeeffectiveNode () const
 Returns a reference to the simplest node which represents this node, after any compilation optimizations have been applied. More...
 
QVariant eval (QgsExpression *parent, const QgsExpressionContext *context)
 Evaluate this node with the given context and parent. More...
 
bool hasCachedStaticValue () const
 Returns true if the node can be replaced by a static cached value. More...
 
virtual bool isStatic (QgsExpression *parent, const QgsExpressionContext *context) const =0
 Returns true if this node can be evaluated for a static value. More...
 
virtual bool needsGeometry () const =0
 Abstract virtual method which returns if the geometry is required to evaluate this expression. More...
 
virtual QList< const QgsExpressionNode * > nodes () const =0
 Returns a list of all nodes which are used in this expression. More...
 
virtual QgsExpressionNode::NodeType nodeType () const =0
 Gets the type of this node. More...
 
bool prepare (QgsExpression *parent, const QgsExpressionContext *context)
 Prepare this node for evaluation. More...
 
virtual QSet< QString > referencedColumns () const =0
 Abstract virtual method which returns a list of columns required to evaluate this node. More...
 
virtual QSet< QString > referencedFunctions () const =0
 Returns a set of all functions which are used in this expression. More...
 
virtual QSet< QString > referencedVariables () const =0
 Returns a set of all variables which are used in this expression. More...
 

Public Attributes

int parserFirstColumn = 0
 First column in the parser this node was found. More...
 
int parserFirstLine = 0
 First line in the parser this node was found. More...
 
int parserLastColumn = 0
 Last column in the parser this node was found. More...
 
int parserLastLine = 0
 Last line in the parser this node was found. More...
 

Protected Member Functions

 QgsExpressionNode ()=default
 Constructor. More...
 
 QgsExpressionNode (const QgsExpressionNode &other)
 Copy constructor. More...
 
void cloneTo (QgsExpressionNode *target) const
 Copies the members of this node to the node provided in target. More...
 
QgsExpressionNodeoperator= (const QgsExpressionNode &other)
 Assignment operator. More...
 

Protected Attributes

QVariant mCachedStaticValue
 Contains the static, precalculated value for the node if mHasCachedValue is true. More...
 
std::unique_ptr< QgsExpressionNodemCompiledSimplifiedNode
 Contains a compiled node which represents a simplified version of this node as a result of compilation optimizations. More...
 
bool mHasCachedValue = false
 true if the node has a static, precalculated value. More...
 

Detailed Description

Abstract base class for all nodes that can appear in an expression.

Definition at line 34 of file qgsexpressionnode.h.

Member Enumeration Documentation

◆ NodeType

Known node types.

Enumerator
ntUnaryOperator 
See also
QgsExpression::Node::NodeUnaryOperator
ntBinaryOperator 
See also
QgsExpression::Node::NodeBinaryOperator
ntInOperator 
See also
QgsExpression::Node::NodeInOperator
ntFunction 
See also
QgsExpression::Node::NodeFunction
ntLiteral 
See also
QgsExpression::Node::NodeLiteral
ntColumnRef 
See also
QgsExpression::Node::NodeColumnRef
ntCondition 
See also
QgsExpression::Node::NodeCondition
ntIndexOperator 

Index operator.

Definition at line 74 of file qgsexpressionnode.h.

Constructor & Destructor Documentation

◆ ~QgsExpressionNode()

virtual QgsExpressionNode::~QgsExpressionNode ( )
virtualdefault

◆ QgsExpressionNode() [1/2]

QgsExpressionNode::QgsExpressionNode ( )
protecteddefault

Constructor.

◆ QgsExpressionNode() [2/2]

QgsExpressionNode::QgsExpressionNode ( const QgsExpressionNode other)
protected

Copy constructor.

Definition at line 59 of file qgsexpressionnode.cpp.

Member Function Documentation

◆ cachedStaticValue()

QVariant QgsExpressionNode::cachedStaticValue ( ) const
inline

Returns the node's static cached value.

Only valid if hasCachedStaticValue() is true.

See also
hasCachedStaticValue()
Since
QGIS 3.18

Definition at line 330 of file qgsexpressionnode.h.

◆ clone()

virtual QgsExpressionNode* QgsExpressionNode::clone ( ) const
pure virtual

◆ cloneTo()

void QgsExpressionNode::cloneTo ( QgsExpressionNode target) const
protected

Copies the members of this node to the node provided in target.

Needs to be called by all subclasses as part of their clone() implementation.

Note
Not available in python bindings, QgsExpression::Node is not going to be subclassed from python. If that's what you are looking for, look into writing a custom python expression function.
Since
QGIS 3.0

Definition at line 83 of file qgsexpressionnode.cpp.

◆ dump()

virtual QString QgsExpressionNode::dump ( ) const
pure virtual

Dump this node into a serialized (part) of an expression.

The returned expression does not necessarily literally match the original expression, it's just guaranteed to behave the same way.

Implemented in QgsExpressionNodeCondition, QgsExpressionNodeColumnRef, QgsExpressionNodeLiteral, QgsExpressionNodeFunction, QgsExpressionNodeInOperator, QgsExpressionNodeIndexOperator, QgsExpressionNodeBinaryOperator, and QgsExpressionNodeUnaryOperator.

◆ effectiveNode()

const QgsExpressionNode* QgsExpressionNode::effectiveNode ( ) const
inline

Returns a reference to the simplest node which represents this node, after any compilation optimizations have been applied.

Eg. a node like "CASE WHEN true THEN "some_field" WHEN other condition THEN ... END" can effectively be replaced entirely by a QgsExpressionNodeColumnRef referencing the "some_field" field, as the CASE WHEN ... will ALWAYS evaluate to "some_field".

Returns a reference to the current object if no optimizations were applied.

Since
QGIS 3.20

Definition at line 344 of file qgsexpressionnode.h.

◆ eval()

QVariant QgsExpressionNode::eval ( QgsExpression parent,
const QgsExpressionContext context 
)

Evaluate this node with the given context and parent.

This will return a cached value if it has been determined to be static during the prepare() execution.

Since
QGIS 2.12

Definition at line 20 of file qgsexpressionnode.cpp.

◆ hasCachedStaticValue()

bool QgsExpressionNode::hasCachedStaticValue ( ) const
inline

Returns true if the node can be replaced by a static cached value.

See also
cachedStaticValue()
Since
QGIS 3.18

Definition at line 322 of file qgsexpressionnode.h.

◆ isStatic()

virtual bool QgsExpressionNode::isStatic ( QgsExpression parent,
const QgsExpressionContext context 
) const
pure virtual

Returns true if this node can be evaluated for a static value.

This is used during the prepare() step and in case it returns true, the value of this node will already be evaluated and the result cached (and therefore not re-evaluated in subsequent calls to eval()). In case this returns true, prepareNode() will never be called.

Since
QGIS 3.0

Implemented in QgsExpressionNodeCondition, QgsExpressionNodeColumnRef, QgsExpressionNodeLiteral, QgsExpressionNodeFunction, QgsExpressionNodeInOperator, QgsExpressionNodeIndexOperator, QgsExpressionNodeBinaryOperator, and QgsExpressionNodeUnaryOperator.

◆ needsGeometry()

virtual bool QgsExpressionNode::needsGeometry ( ) const
pure virtual

Abstract virtual method which returns if the geometry is required to evaluate this expression.

This needs to call needsGeometry() recursively on any child nodes.

Returns
true if a geometry is required to evaluate this expression

Implemented in QgsExpressionNodeCondition, QgsExpressionNodeColumnRef, QgsExpressionNodeLiteral, QgsExpressionNodeFunction, QgsExpressionNodeInOperator, QgsExpressionNodeIndexOperator, QgsExpressionNodeBinaryOperator, and QgsExpressionNodeUnaryOperator.

◆ nodes()

virtual QList<const QgsExpressionNode *> QgsExpressionNode::nodes ( ) const
pure virtual

Returns a list of all nodes which are used in this expression.

Note
not available in Python bindings
Since
QGIS 3.2

Implemented in QgsExpressionNodeCondition, QgsExpressionNodeColumnRef, QgsExpressionNodeLiteral, QgsExpressionNodeFunction, QgsExpressionNodeInOperator, QgsExpressionNodeIndexOperator, QgsExpressionNodeBinaryOperator, and QgsExpressionNodeUnaryOperator.

◆ nodeType()

virtual QgsExpressionNode::NodeType QgsExpressionNode::nodeType ( ) const
pure virtual

◆ operator=()

QgsExpressionNode & QgsExpressionNode::operator= ( const QgsExpressionNode other)
protected

Assignment operator.

Definition at line 71 of file qgsexpressionnode.cpp.

◆ prepare()

bool QgsExpressionNode::prepare ( QgsExpression parent,
const QgsExpressionContext context 
)

Prepare this node for evaluation.

This will check if the node content is static and in this case cache the value. If it's not static it will call prepareNode() to allow the node to do initialization work like for example resolving a column name to an attribute index.

Since
QGIS 2.12

Definition at line 37 of file qgsexpressionnode.cpp.

◆ referencedColumns()

virtual QSet<QString> QgsExpressionNode::referencedColumns ( ) const
pure virtual

Abstract virtual method which returns a list of columns required to evaluate this node.

When reimplementing this, you need to return any column that is required to evaluate this node and in addition recursively collect all the columns required to evaluate child nodes.

Warning
If the expression has been prepared via a call to QgsExpression::prepare(), or a call to QgsExpressionNode::prepare() for a node has been made, then some nodes in the expression may have been determined to evaluate to a static pre-calculatable value. In this case the results will omit attribute indices which are used by these pre-calculated nodes, regardless of their actual referenced columns. If you are seeking to use these functions to introspect an expression you must take care to do this with an unprepared expression node.
Returns
A list of columns required to evaluate this expression

Implemented in QgsExpressionNodeCondition, QgsExpressionNodeColumnRef, QgsExpressionNodeLiteral, QgsExpressionNodeFunction, QgsExpressionNodeInOperator, QgsExpressionNodeIndexOperator, QgsExpressionNodeBinaryOperator, and QgsExpressionNodeUnaryOperator.

◆ referencedFunctions()

virtual QSet<QString> QgsExpressionNode::referencedFunctions ( ) const
pure virtual

Returns a set of all functions which are used in this expression.

Note
In contrast to the referencedColumns() function this method is not affected by any previous calls to QgsExpressionNode::prepare().

Implemented in QgsExpressionNodeCondition, QgsExpressionNodeColumnRef, QgsExpressionNodeLiteral, QgsExpressionNodeFunction, QgsExpressionNodeInOperator, QgsExpressionNodeIndexOperator, QgsExpressionNodeBinaryOperator, and QgsExpressionNodeUnaryOperator.

◆ referencedVariables()

virtual QSet<QString> QgsExpressionNode::referencedVariables ( ) const
pure virtual

Returns a set of all variables which are used in this expression.

Note
In contrast to the referencedColumns() function this method is not affected by any previous calls to QgsExpressionNode::prepare().

Implemented in QgsExpressionNodeCondition, QgsExpressionNodeColumnRef, QgsExpressionNodeLiteral, QgsExpressionNodeFunction, QgsExpressionNodeInOperator, QgsExpressionNodeIndexOperator, QgsExpressionNodeBinaryOperator, and QgsExpressionNodeUnaryOperator.

Member Data Documentation

◆ mCachedStaticValue

QVariant QgsExpressionNode::mCachedStaticValue
mutableprotected

Contains the static, precalculated value for the node if mHasCachedValue is true.

Since
QGIS 3.20

Definition at line 383 of file qgsexpressionnode.h.

◆ mCompiledSimplifiedNode

std::unique_ptr< QgsExpressionNode > QgsExpressionNode::mCompiledSimplifiedNode
mutableprotected

Contains a compiled node which represents a simplified version of this node as a result of compilation optimizations.

Eg. a node like "CASE WHEN true THEN "some_field" WHEN other condition THEN ... END" can effectively be replaced entirely by a QgsExpressionNodeColumnRef referencing the "some_field" field, as the CASE WHEN ... will ALWAYS evaluate to "some_field".

Since
QGIS 3.20

Definition at line 395 of file qgsexpressionnode.h.

◆ mHasCachedValue

bool QgsExpressionNode::mHasCachedValue = false
mutableprotected

true if the node has a static, precalculated value.

Since
QGIS 3.20

Definition at line 376 of file qgsexpressionnode.h.

◆ parserFirstColumn

int QgsExpressionNode::parserFirstColumn = 0

First column in the parser this node was found.

Note
This might not be complete for all nodes. Currently only
See also
QgsExpressionNode has this complete

Definition at line 300 of file qgsexpressionnode.h.

◆ parserFirstLine

int QgsExpressionNode::parserFirstLine = 0

First line in the parser this node was found.

Note
This might not be complete for all nodes. Currently only
See also
QgsExpressionNode has this complete

Definition at line 293 of file qgsexpressionnode.h.

◆ parserLastColumn

int QgsExpressionNode::parserLastColumn = 0

Last column in the parser this node was found.

Note
This might not be complete for all nodes. Currently only
See also
QgsExpressionNode has this complete

Definition at line 314 of file qgsexpressionnode.h.

◆ parserLastLine

int QgsExpressionNode::parserLastLine = 0

Last line in the parser this node was found.

Note
This might not be complete for all nodes. Currently only
See also
QgsExpressionNode has this complete

Definition at line 307 of file qgsexpressionnode.h.


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