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

#include <qgsexpressionnode.h>

Inheritance diagram for QgsExpressionNode:

[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 , ntBetweenOperator }
	Known node types. More...

Public Member Functions
virtual	~QgsExpressionNode ()=default

QVariant	cachedStaticValue () const
	Returns the node's static cached value. More...

virtual QgsExpressionNode *	clone () 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 QgsExpressionNode *	effectiveNode () 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...

void	setCachedStaticValue (const QVariant &value) const
	Sets the cached static value for the node. 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...

QgsExpressionNode &	operator= (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< QgsExpressionNode >	mCompiledSimplifiedNode
	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

enum QgsExpressionNode::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.
ntBetweenOperator	Between operator. Since QGIS 3.26

Definition at line 77 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 65 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 333 of file qgsexpressionnode.h.

◆ clone()

virtual QgsExpressionNode * QgsExpressionNode::clone ( ) const

pure virtual

Generate a clone of this node.

Ownership is transferred to the caller.

Returns: a deep copy of this node.

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

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

Definition at line 89 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 QgsExpressionNodeUnaryOperator, QgsExpressionNodeBinaryOperator, QgsExpressionNodeIndexOperator, QgsExpressionNodeBetweenOperator, QgsExpressionNodeInOperator, QgsExpressionNodeFunction, QgsExpressionNodeLiteral, QgsExpressionNodeColumnRef, and QgsExpressionNodeCondition.

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

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

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

◆ 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 QgsExpressionNodeUnaryOperator, QgsExpressionNodeBinaryOperator, QgsExpressionNodeIndexOperator, QgsExpressionNodeBetweenOperator, QgsExpressionNodeInOperator, QgsExpressionNodeFunction, QgsExpressionNodeLiteral, QgsExpressionNodeColumnRef, and QgsExpressionNodeCondition.

◆ 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 QgsExpressionNodeUnaryOperator, QgsExpressionNodeBinaryOperator, QgsExpressionNodeIndexOperator, QgsExpressionNodeBetweenOperator, QgsExpressionNodeInOperator, QgsExpressionNodeFunction, QgsExpressionNodeLiteral, QgsExpressionNodeColumnRef, and QgsExpressionNodeCondition.

◆ nodeType()

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

pure virtual

Gets the type of this node.

Returns: The type of this node

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

◆ operator=()

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

protected

Assignment operator.

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

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 QgsExpressionNodeUnaryOperator, QgsExpressionNodeBinaryOperator, QgsExpressionNodeIndexOperator, QgsExpressionNodeBetweenOperator, QgsExpressionNodeInOperator, QgsExpressionNodeFunction, QgsExpressionNodeLiteral, QgsExpressionNodeColumnRef, and QgsExpressionNodeCondition.

◆ 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 QgsExpressionNodeUnaryOperator, QgsExpressionNodeBinaryOperator, QgsExpressionNodeIndexOperator, QgsExpressionNodeBetweenOperator, QgsExpressionNodeInOperator, QgsExpressionNodeFunction, QgsExpressionNodeLiteral, QgsExpressionNodeColumnRef, and QgsExpressionNodeCondition.

◆ 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 QgsExpressionNodeUnaryOperator, QgsExpressionNodeBinaryOperator, QgsExpressionNodeIndexOperator, QgsExpressionNodeBetweenOperator, QgsExpressionNodeInOperator, QgsExpressionNodeFunction, QgsExpressionNodeLiteral, QgsExpressionNodeColumnRef, and QgsExpressionNodeCondition.

◆ setCachedStaticValue()

void QgsExpressionNode::setCachedStaticValue ( const QVariant & value ) const

Sets the cached static value for the node.

Note: Not available from Python bindings.

Since: QGIS 3.30

Definition at line 59 of file qgsexpressionnode.cpp.

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 394 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 406 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 387 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 303 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 296 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 317 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 310 of file qgsexpressionnode.h.

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

/build/qgis-3.37.0+git20240325+fdefdf9c27f+17bookworm/src/core/expression/qgsexpressionnode.h
/build/qgis-3.37.0+git20240325+fdefdf9c27f+17bookworm/src/core/expression/qgsexpressionnode.cpp

Classes

Public Types

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ NodeType

Constructor & Destructor Documentation

◆ ~QgsExpressionNode()

◆ QgsExpressionNode() [1/2]

◆ QgsExpressionNode() [2/2]

Member Function Documentation

◆ cachedStaticValue()

◆ clone()

◆ cloneTo()

◆ dump()

◆ effectiveNode()

◆ eval()

◆ hasCachedStaticValue()

◆ isStatic()

◆ needsGeometry()

◆ nodes()

◆ nodeType()

◆ operator=()

◆ prepare()

◆ referencedColumns()

◆ referencedFunctions()

◆ referencedVariables()

◆ setCachedStaticValue()

Member Data Documentation

◆ mCachedStaticValue

◆ mCompiledSimplifiedNode

◆ mHasCachedValue

◆ parserFirstColumn

◆ parserFirstLine

◆ parserLastColumn

◆ parserLastLine