Class for parsing and evaluation of expressions (formerly called "search strings"). More...

#include <qgsexpression.h>

Classes
struct	ParserError
	Details about any parser errors that were found when parsing the expression. More...

Public Types
enum	SpatialOperator { soBbox , soIntersects , soContains , soCrosses , soEquals , soDisjoint , soOverlaps , soTouches , soWithin }

Public Member Functions
	QgsExpression ()
	Create an empty expression. More...

	QgsExpression (const QgsExpression &other)
	Create a copy of this expression. More...

	QgsExpression (const QString &expr)
	Creates a new expression based on the provided string. More...

	~QgsExpression ()

QgsUnitTypes::AreaUnit	areaUnits () const
	Returns the desired areal units for calculations involving geomCalculator(), e.g., "$area". More...

QgsUnitTypes::DistanceUnit	distanceUnits () const
	Returns the desired distance units for calculations involving geomCalculator(), e.g., "$length" and "$perimeter". More...

QString	dump () const
	Returns an expression string, constructed from the internal abstract syntax tree. More...

QString	evalErrorString () const
	Returns evaluation error. More...

QVariant	evaluate ()
	Evaluate the feature and return the result. More...

QVariant	evaluate (const QgsExpressionContext *context)
	Evaluate the expression against the specified context and return the result. More...

QString	expression () const
	Returns the original, unmodified expression string. More...

template<class T >
QList< const T * >	findNodes () const
	Returns a list of all nodes of the given class which are used in this expression. More...

QgsDistanceArea *	geomCalculator ()
	Returns calculator used for distance and area calculations (used by $length, $area and $perimeter functions only) More...

bool	hasEvalError () const
	Returns `true` if an error occurred when evaluating last input. More...

bool	hasParserError () const
	Returns `true` if an error occurred when parsing the input expression. More...

bool	isField () const
	Checks whether an expression consists only of a single field reference. More...

bool	isValid () const
	Checks if this expression is valid. More...

bool	needsGeometry () const
	Returns `true` if the expression uses feature geometry for some computation. More...

QList< const QgsExpressionNode * >	nodes () const
	Returns a list of all nodes which are used in this expression. More...

	operator QString () const
	Automatically convert this expression to a string where requested. More...

QgsExpression &	operator= (const QgsExpression &other)
	Create a copy of this expression. More...

bool	operator== (const QgsExpression &other) const
	Compares two expressions. More...

QList< QgsExpression::ParserError >	parserErrors () const
	Returns parser error details including location of error. More...

QString	parserErrorString () const
	Returns parser error. More...

bool	prepare (const QgsExpressionContext *context)
	Gets the expression ready for evaluation - find out column indexes. More...

QSet< int >	referencedAttributeIndexes (const QgsFields &fields) const
	Returns a list of field name indexes obtained from the provided fields. More...

QSet< QString >	referencedColumns () const
	Gets list of columns referenced by the expression. More...

QSet< QString >	referencedFunctions () const
	Returns a list of the names of all functions which are used in this expression. More...

QSet< QString >	referencedVariables () const
	Returns a list of all variables which are used in this expression. More...

const QgsExpressionNode *	rootNode () const
	Returns the root node of the expression. More...

void	setAreaUnits (QgsUnitTypes::AreaUnit unit)
	Sets the desired areal units for calculations involving geomCalculator(), e.g., "$area". More...

void	setDistanceUnits (QgsUnitTypes::DistanceUnit unit)
	Sets the desired distance units for calculations involving geomCalculator(), e.g., "$length" and "$perimeter". More...

void	setEvalErrorString (const QString &str)
	Sets evaluation error (used internally by evaluation functions) More...

void	setExpression (const QString &expression)
	Set the expression string, will reset the whole internal structure. More...

void	setGeomCalculator (const QgsDistanceArea *calc)
	Sets the geometry calculator used for distance and area calculations in expressions. More...

Static Public Member Functions
static bool	addVariableHelpText (const QString name, const QString &description)
	Adds a help string for a custom variable. More...

static bool	attemptReduceToInClause (const QStringList &expressions, QString &result)
	Attempts to reduce a list of expressions to a single "field IN (val1, val2, ... )" type expression. More...

static const QStringList &	BuiltinFunctions ()

static bool	checkExpression (const QString &text, const QgsExpressionContext *context, QString &errorMessage)
	Tests whether a string is a valid expression. More...

static void	cleanRegisteredFunctions ()
	Deletes all registered functions whose ownership have been transferred to the expression engine. More...

static QString	createFieldEqualityExpression (const QString &fieldName, const QVariant &value)
	Create an expression allowing to evaluate if a field is equal to a value. More...

static double	evaluateToDouble (const QString &text, double fallbackValue)
	Attempts to evaluate a text string as an expression to a resultant double value. More...

static int	expressionToLayerFieldIndex (const QString &expression, const QgsVectorLayer *layer)
	Attempts to resolve an expression to a field index from the given layer. More...

static QString	formatPreviewString (const QVariant &value, bool htmlOutput=true, int maximumPreviewLength=60)
	Formats an expression result for friendly display to the user. More...

static QString	formatVariableHelp (const QString &description, bool showValue=true, const QVariant &value=QVariant())
	Returns formatted help text for a variable. More...

static int	functionCount ()
	Returns the number of functions defined in the parser. More...

static int	functionIndex (const QString &name)
	Returns index of the function in Functions array. More...

static const QList< QgsExpressionFunction * > &	Functions ()

static QString	group (const QString &group)
	Returns the translated name for a function group. More...

static QString	helpText (QString name)
	Returns the help text for a specified function. More...

static bool	isFieldEqualityExpression (const QString &expression, QString &field, QVariant &value)
	Returns `true` if the given expression is a simple "field=value" type expression. More...

static bool	isFunctionName (const QString &name)
	tells whether the identifier is a name of existing function More...

static QString	quotedColumnRef (QString name)
	Returns a quoted column reference (in double quotes) More...

static QString	quotedString (QString text)
	Returns a quoted version of a string (in single quotes) More...

static QString	quotedValue (const QVariant &value)
	Returns a string representation of a literal value, including appropriate quotations where required. More...

static QString	quotedValue (const QVariant &value, QVariant::Type type)
	Returns a string representation of a literal value, including appropriate quotations where required. More...

static QSet< QString >	referencedVariables (const QString &text)
	This function returns variables in each expression between [% and %]. More...

static bool	registerFunction (QgsExpressionFunction *function, bool transferOwnership=false)
	Registers a function to the expression engine. More...

static QString	replaceExpressionText (const QString &action, const QgsExpressionContext context, const QgsDistanceArea distanceArea=nullptr)
	This function replaces each expression between [% and %] in the string with the result of its evaluation with the specified context. More...

static QStringList	tags (const QString &name)
	Returns a string list of search tags for a specified function. More...

static bool	unregisterFunction (const QString &name)
	Unregisters a function from the expression engine. More...

static QString	variableHelpText (const QString &variableName)
	Returns the help text for a specified variable. More...

Friends
class	QgsOgcUtils

Detailed Description

Class for parsing and evaluation of expressions (formerly called "search strings").

The expressions try to follow both syntax and semantics of SQL expressions.

Usage:

exp = QgsExpression("gid*2 > 10 and type not in ('D','F')")
if exp.hasParserError():
    # show error message with parserErrorString() and exit
 
result = exp.evaluate(feature, fields)
if exp.hasEvalError():
    # show error message with evalErrorString()
else:
    # examine the result

Three Value Logic

Similarly to SQL, this class supports three-value logic: true/false/unknown. Unknown value may be a result of operations with missing data (NULL). Please note that NULL is different value than zero or an empty string. For example 3 > NULL returns unknown.

There is no special (three-value) 'boolean' type: true/false is represented as 1/0 integer, unknown value is represented the same way as NULL values: NULL QVariant.

Performance

For better performance with many evaluations you may first call prepare(fields) function to find out indices of columns and then repeatedly call evaluate(feature).

Type conversion

Operators and functions that expect arguments to be of a particular type automatically convert the arguments to that type, e.g. sin('2.1') will convert the argument to a double, length(123) will first convert the number to a string. Explicit conversion can be achieved with to_int, to_real, to_string functions. If implicit or explicit conversion is invalid, the evaluation returns an error. Comparison operators do numeric comparison in case both operators are numeric (int/double) or they can be converted to numeric types.

Implicit sharing

This class is implicitly shared, copying has a very low overhead. It is normally preferable to call QgsExpression( otherExpression ) instead of QgsExpression( otherExpression.expression() ). A deep copy will only be made when prepare() is called. For usage this means mainly, that you should normally keep an unprepared master copy of a QgsExpression and whenever using it with a particular QgsFeatureIterator copy it just before and prepare it using the same context as the iterator.

Implicit sharing was added in 2.14

Definition at line 102 of file qgsexpression.h.

Member Enumeration Documentation

◆ SpatialOperator

enum QgsExpression::SpatialOperator

Enumerator
soBbox
soIntersects
soContains
soCrosses
soEquals
soDisjoint
soOverlaps
soTouches
soWithin

Definition at line 503 of file qgsexpression.h.

Constructor & Destructor Documentation

◆ QgsExpression() [1/3]

QgsExpression::QgsExpression ( const QString & expr )

Creates a new expression based on the provided string.

The string will immediately be parsed. For optimization prepare() should always be called before every loop in which this expression is used.

Definition at line 149 of file qgsexpression.cpp.

◆ QgsExpression() [2/3]

QgsExpression::QgsExpression ( const QgsExpression & other )

Create a copy of this expression.

This is preferred over recreating an expression from a string since it does not need to be re-parsed.

Definition at line 157 of file qgsexpression.cpp.

◆ QgsExpression() [3/3]

QgsExpression::QgsExpression ( )

Create an empty expression.

Since: QGIS 3.0

Definition at line 183 of file qgsexpression.cpp.

◆ ~QgsExpression()

QgsExpression::~QgsExpression ( )

Definition at line 188 of file qgsexpression.cpp.

Member Function Documentation

◆ addVariableHelpText()

bool QgsExpression::addVariableHelpText	(	const QString	name,
		const QString &	description
	)

static

Adds a help string for a custom variable.

The specified variable name should not have an existing help string set. If a help string is already present then false will be returned and no changes will occur.

Parameters

name	variable name
description	the help string to add. This is user visible, and should be a translated string.

Returns: true if the help string was successfully added

See also: variableHelpText()

Since: QGIS 3.22

Definition at line 904 of file qgsexpression.cpp.

◆ areaUnits()

QgsUnitTypes::AreaUnit QgsExpression::areaUnits ( ) const

Returns the desired areal units for calculations involving geomCalculator(), e.g., "$area".

Note: areas are only converted when a geomCalculator() has been set

See also: setAreaUnits(); distanceUnits()

Since: QGIS 2.14

Definition at line 423 of file qgsexpression.cpp.

◆ attemptReduceToInClause()

bool QgsExpression::attemptReduceToInClause	(	const QStringList &	expressions,
		QString &	result
	)

static

Attempts to reduce a list of expressions to a single "field IN (val1, val2, ... )" type expression.

This will only be possible if all the input expressions form simple "field=value" OR "field IN (value1, value2)" expressions, and all reference the same field name.

Returns true if the given expressions could be converted to an IN type expression.

Parameters

expressions	expressions to test
result	will be set to the calculated "field IN (...)" expression, wherever possible

Returns: true if the expression was converted to a field IN type expression

Since: QGIS 3.18

Definition at line 1156 of file qgsexpression.cpp.

◆ BuiltinFunctions()

const QStringList & QgsExpression::BuiltinFunctions ( )

static

Definition at line 7568 of file qgsexpressionfunction.cpp.

◆ checkExpression()

bool QgsExpression::checkExpression	(	const QString &	text,
		const QgsExpressionContext *	context,
		QString &	errorMessage
	)

static

Tests whether a string is a valid expression.

Parameters

text	string to test
context	optional expression context
errorMessage	will be filled with any error message from the validation

Returns: true if string is a valid expression

Since: QGIS 2.12

Definition at line 43 of file qgsexpression.cpp.

◆ cleanRegisteredFunctions()

void QgsExpression::cleanRegisteredFunctions ( )

static

Deletes all registered functions whose ownership have been transferred to the expression engine.

Since: QGIS 2.12

Definition at line 7562 of file qgsexpressionfunction.cpp.

◆ createFieldEqualityExpression()

QString QgsExpression::createFieldEqualityExpression	(	const QString &	fieldName,
		const QVariant &	value
	)

static

Create an expression allowing to evaluate if a field is equal to a value.

The value may be null.

Parameters

fieldName	the name of the field
value	the value of the field

Returns: the expression to evaluate field equality

Since: QGIS 3.0

Definition at line 1120 of file qgsexpression.cpp.

◆ distanceUnits()

QgsUnitTypes::DistanceUnit QgsExpression::distanceUnits ( ) const

Returns the desired distance units for calculations involving geomCalculator(), e.g., "$length" and "$perimeter".

Note: distances are only converted when a geomCalculator() has been set

See also: setDistanceUnits(); areaUnits()

Since: QGIS 2.14

Definition at line 413 of file qgsexpression.cpp.

◆ dump()

QString QgsExpression::dump ( ) const

Returns an expression string, constructed from the internal abstract syntax tree.

This does not contain any nice whitespace formatting or comments. In general it is preferable to use expression() instead.

Definition at line 392 of file qgsexpression.cpp.

◆ evalErrorString()

QString QgsExpression::evalErrorString ( ) const

Returns evaluation error.

Definition at line 382 of file qgsexpression.cpp.

◆ evaluate() [1/2]

QVariant QgsExpression::evaluate ( )

Evaluate the feature and return the result.

Note: this method does not expect that prepare() has been called on this instance

Since: QGIS 2.12

Definition at line 349 of file qgsexpression.cpp.

◆ evaluate() [2/2]

QVariant QgsExpression::evaluate ( const QgsExpressionContext * context )

Evaluate the expression against the specified context and return the result.

Parameters

context context for evaluating expression

Note: prepare() should be called before calling this method.

Since: QGIS 2.12

Definition at line 361 of file qgsexpression.cpp.

◆ evaluateToDouble()

double QgsExpression::evaluateToDouble	(	const QString &	text,
		double	fallbackValue
	)

static

Attempts to evaluate a text string as an expression to a resultant double value.

Parameters

text	text to evaluate as expression
fallbackValue	value to return if text can not be evaluated as a double

Returns: evaluated double value, or fallback value

Note: this method is inefficient for bulk evaluation of expressions, it is intended for one-off evaluations only.

Since: QGIS 2.7

Definition at line 517 of file qgsexpression.cpp.

◆ expression()

QString QgsExpression::expression ( ) const

Returns the original, unmodified expression string.

If there was none supplied because it was constructed by sole API calls, dump() will be used to create one instead.

Definition at line 60 of file qgsexpression.cpp.

◆ expressionToLayerFieldIndex()

int QgsExpression::expressionToLayerFieldIndex	(	const QString &	expression,
		const QgsVectorLayer *	layer
	)

static

Attempts to resolve an expression to a field index from the given layer.

Given a string which may either directly match a field name from a layer, OR may be an expression which consists only of a single field reference for that layer, this method will return the corresponding field index.

Returns: field index if found, or -1 if expression does not represent a field from the layer.

See also: isField()

Since: QGIS 3.22

Definition at line 1357 of file qgsexpression.cpp.

◆ findNodes()

template<class T >

QList<const T *> QgsExpression::findNodes ( ) const

inline

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

Note: not available in Python bindings

Since: QGIS 3.2

Definition at line 294 of file qgsexpression.h.

◆ formatPreviewString()

QString QgsExpression::formatPreviewString	(	const QVariant &	value,
		bool	htmlOutput = `true`,
		int	maximumPreviewLength = `60`
	)

static

Formats an expression result for friendly display to the user.

Truncates the result to a sensible length, and presents text representations of non numeric/text types (e.g., geometries and features).

Parameters

value	expression result to format
htmlOutput	set to `true` to allow HTML formatting, or `false` for plain text output
maximumPreviewLength	define the maximum character length of the preview

Returns: formatted string, may contain HTML formatting characters if htmlOutput is true

Since: QGIS 2.14

Definition at line 972 of file qgsexpression.cpp.

◆ formatVariableHelp()

QString QgsExpression::formatVariableHelp	(	const QString &	description,
		bool	showValue = `true`,
		const QVariant &	value = `QVariant()`
	)

static

Returns formatted help text for a variable.

Parameters

description	translated description of variable
showValue	set to `true` to include current value of variable in help text
value	current value of variable to show in help text

See also: helpText(); variableHelpText()

Since: QGIS 3.0

Definition at line 920 of file qgsexpression.cpp.

◆ functionCount()

int QgsExpression::functionCount ( )

static

Returns the number of functions defined in the parser.

Returns: The number of function defined in the parser.

Definition at line 143 of file qgsexpression.cpp.

◆ functionIndex()

int QgsExpression::functionIndex ( const QString & name )

static

Returns index of the function in Functions array.

Definition at line 126 of file qgsexpression.cpp.

◆ Functions()

const QList< QgsExpressionFunction * > & QgsExpression::Functions ( )

static

Definition at line 6517 of file qgsexpressionfunction.cpp.

◆ geomCalculator()

QgsDistanceArea * QgsExpression::geomCalculator ( )

Returns calculator used for distance and area calculations (used by $length, $area and $perimeter functions only)

See also: setGeomCalculator(); distanceUnits(); areaUnits()

Definition at line 400 of file qgsexpression.cpp.

◆ group()

QString QgsExpression::group ( const QString & group )

static

Returns the translated name for a function group.

Parameters

group untranslated group name

Definition at line 939 of file qgsexpression.cpp.

◆ hasEvalError()

bool QgsExpression::hasEvalError ( ) const

Returns true if an error occurred when evaluating last input.

Definition at line 377 of file qgsexpression.cpp.

◆ hasParserError()

bool QgsExpression::hasParserError ( ) const

Returns true if an error occurred when parsing the input expression.

Definition at line 205 of file qgsexpression.cpp.

◆ helpText()

QString QgsExpression::helpText ( QString name )

static

Returns the help text for a specified function.

Parameters

name	function name

See also: variableHelpText(); formatVariableHelp()

Definition at line 545 of file qgsexpression.cpp.

◆ isField()

bool QgsExpression::isField ( ) const

Checks whether an expression consists only of a single field reference.

See also: expressionToLayerFieldIndex()

Since: QGIS 2.9

Definition at line 1352 of file qgsexpression.cpp.

◆ isFieldEqualityExpression()

bool QgsExpression::isFieldEqualityExpression	(	const QString &	expression,
		QString &	field,
		QVariant &	value
	)

static

Returns true if the given expression is a simple "field=value" type expression.

Parameters

expression	expression to test
field	will be set to the field name if the expression is a field equality expression
value	will be set to the value if the expression is a field equality expression

Returns: true if the expression is a field equality expression

Since: QGIS 3.18

Definition at line 1132 of file qgsexpression.cpp.

◆ isFunctionName()

bool QgsExpression::isFunctionName ( const QString & name )

static

tells whether the identifier is a name of existing function

Definition at line 121 of file qgsexpression.cpp.

◆ isValid()

bool QgsExpression::isValid ( ) const

Checks if this expression is valid.

A valid expression could be parsed but does not necessarily evaluate properly.

Since: QGIS 3.0

Definition at line 200 of file qgsexpression.cpp.

◆ needsGeometry()

bool QgsExpression::needsGeometry ( ) const

Returns true if the expression uses feature geometry for some computation.

Definition at line 269 of file qgsexpression.cpp.

◆ nodes()

QList< const QgsExpressionNode * > QgsExpression::nodes ( ) const

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

Note: not available in Python bindings

Since: QGIS 3.2

Definition at line 1377 of file qgsexpression.cpp.

◆ operator QString()

QgsExpression::operator QString ( ) const

Automatically convert this expression to a string where requested.

Since: QGIS 3.0

Definition at line 178 of file qgsexpression.cpp.

◆ operator=()

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

Create a copy of this expression.

This is preferred over recreating an expression from a string since it does not need to be re-parsed.

Definition at line 163 of file qgsexpression.cpp.

◆ operator==()

bool QgsExpression::operator== ( const QgsExpression & other ) const

Compares two expressions.

The operator returns true if the expression string is equal.

Since: QGIS 3.0

Definition at line 195 of file qgsexpression.cpp.

◆ parserErrors()

QList< QgsExpression::ParserError > QgsExpression::parserErrors ( ) const

Returns parser error details including location of error.

Since: QGIS 3.0

Definition at line 215 of file qgsexpression.cpp.

◆ parserErrorString()

QString QgsExpression::parserErrorString ( ) const

Returns parser error.

Definition at line 210 of file qgsexpression.cpp.

◆ prepare()

bool QgsExpression::prepare ( const QgsExpressionContext * context )

Gets the expression ready for evaluation - find out column indexes.

Parameters

context context for preparing expression

Since: QGIS 2.12

Definition at line 326 of file qgsexpression.cpp.

◆ quotedColumnRef()

QString QgsExpression::quotedColumnRef ( QString name )

static

Returns a quoted column reference (in double quotes)

See also: quotedString(); quotedValue()

Definition at line 68 of file qgsexpression.cpp.

◆ quotedString()

QString QgsExpression::quotedString ( QString text )

static

Returns a quoted version of a string (in single quotes)

See also: quotedValue(); quotedColumnRef()

Definition at line 73 of file qgsexpression.cpp.

◆ quotedValue() [1/2]

QString QgsExpression::quotedValue ( const QVariant & value )

static

Returns a string representation of a literal value, including appropriate quotations where required.

Parameters

value value to convert to a string representation

See also: quotedString(); quotedColumnRef()

Since: QGIS 2.14

Definition at line 82 of file qgsexpression.cpp.

◆ quotedValue() [2/2]

QString QgsExpression::quotedValue	(	const QVariant &	value,
		QVariant::Type	type
	)

static

Returns a string representation of a literal value, including appropriate quotations where required.

Parameters

value	value to convert to a string representation
type	value type

See also: quotedString(); quotedColumnRef()

Since: QGIS 2.14

Definition at line 87 of file qgsexpression.cpp.

◆ referencedAttributeIndexes()

QSet< int > QgsExpression::referencedAttributeIndexes ( const QgsFields & fields ) const

Returns a list of field name indexes obtained from the provided fields.

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 parts of 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.

Since: QGIS 3.0

Definition at line 244 of file qgsexpression.cpp.

◆ referencedColumns()

QSet< QString > QgsExpression::referencedColumns ( ) const

Gets list of columns referenced by the expression.

Note: If the returned list contains the QgsFeatureRequest::AllAttributes constant then all attributes from the layer are required for evaluation of the expression. QgsFeatureRequest::setSubsetOfAttributes automatically handles this case.

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 parts of 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.

See also: referencedAttributeIndexes()

Definition at line 220 of file qgsexpression.cpp.

◆ referencedFunctions()

QSet< QString > QgsExpression::referencedFunctions ( ) const

Returns a list of the names 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 QgsExpression::prepare(), or QgsExpressionNode::prepare().

Since: QGIS 3.2

Definition at line 236 of file qgsexpression.cpp.

◆ referencedVariables() [1/2]

QSet< QString > QgsExpression::referencedVariables ( ) const

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

If the list contains a NULL QString, there is a variable name used which is determined at runtime.

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

Since: QGIS 3.0

Definition at line 228 of file qgsexpression.cpp.

◆ referencedVariables() [2/2]

QSet< QString > QgsExpression::referencedVariables ( const QString & text )

static

This function returns variables in each expression between [% and %].

Parameters

text	The source string in which variables should be searched.

Since: QGIS 3.2

Definition at line 496 of file qgsexpression.cpp.

◆ registerFunction()

bool QgsExpression::registerFunction	(	QgsExpressionFunction *	function,
		bool	transferOwnership = `false`
	)

static

Registers a function to the expression engine.

This is required to allow expressions to utilize the function.

Parameters

function	function to register
transferOwnership	set to `true` to transfer ownership of function to expression engine

Returns: true on successful registration

See also: unregisterFunction

Definition at line 7533 of file qgsexpressionfunction.cpp.

◆ replaceExpressionText()

QString QgsExpression::replaceExpressionText	(	const QString &	action,
		const QgsExpressionContext *	context,
		const QgsDistanceArea *	distanceArea = `nullptr`
	)

static

This function replaces each expression between [% and %] in the string with the result of its evaluation with the specified context.

Additional substitutions can be passed through the substitutionMap parameter

Parameters

action	The source string in which placeholders should be replaced.
context	Expression context
distanceArea	Optional QgsDistanceArea. If specified, the QgsDistanceArea is used for distance and area conversion

Since: QGIS 2.12

Definition at line 433 of file qgsexpression.cpp.

◆ rootNode()

const QgsExpressionNode * QgsExpression::rootNode ( ) const

Returns the root node of the expression.

The root node is nullptr if parsing has failed.

Definition at line 1347 of file qgsexpression.cpp.

◆ setAreaUnits()

void QgsExpression::setAreaUnits ( QgsUnitTypes::AreaUnit unit )

Sets the desired areal units for calculations involving geomCalculator(), e.g., "$area".

If distance units are set to QgsUnitTypes::AreaUnknownUnit (default), prepare() will read variables from the expression context ("project_distance_units") to determine distance units.

Note: areas are only converted when a geomCalculator() has been set

See also: areaUnits(); setDistanceUnits()

Since: QGIS 2.14

Definition at line 428 of file qgsexpression.cpp.

◆ setDistanceUnits()

void QgsExpression::setDistanceUnits ( QgsUnitTypes::DistanceUnit unit )

Sets the desired distance units for calculations involving geomCalculator(), e.g., "$length" and "$perimeter".

If distance units are set to QgsUnitTypes::DistanceUnknownUnit (default), prepare() will read variables from the expression context ("project_distance_units") to determine distance units.

Note: distances are only converted when a geomCalculator() has been set

See also: distanceUnits(); setAreaUnits()

Since: QGIS 2.14

Definition at line 418 of file qgsexpression.cpp.

◆ setEvalErrorString()

void QgsExpression::setEvalErrorString ( const QString & str )

Sets evaluation error (used internally by evaluation functions)

Definition at line 387 of file qgsexpression.cpp.

◆ setExpression()

void QgsExpression::setExpression ( const QString & expression )

Set the expression string, will reset the whole internal structure.

Since: QGIS 3.0

Definition at line 51 of file qgsexpression.cpp.

◆ setGeomCalculator()

void QgsExpression::setGeomCalculator ( const QgsDistanceArea * calc )

Sets the geometry calculator used for distance and area calculations in expressions.

(used by $length, $area and $perimeter functions only). If the geometry calculator is set to nullptr (default), prepare() will read variables from the expression context ("project_ellipsoid", "_project_transform_context" and "_layer_crs") to build a geometry calculator. If these variables does not exist and if setGeomCalculator() is not called, all distance and area calculations are performed using simple Cartesian methods (ie no ellipsoidal calculations).

Parameters

calc	geometry calculator. Ownership is not transferred. Set to `nullptr` to force Cartesian calculations.

See also: geomCalculator()

Definition at line 317 of file qgsexpression.cpp.

◆ tags()

QStringList QgsExpression::tags ( const QString & name )

static

Returns a string list of search tags for a specified function.

Parameters

name	function name

Since: QGIS 3.12

Definition at line 680 of file qgsexpression.cpp.

◆ unregisterFunction()

bool QgsExpression::unregisterFunction ( const QString & name )

static

Unregisters a function from the expression engine.

The function will no longer be usable in expressions.

Parameters

name	function name

See also: registerFunction

Definition at line 7546 of file qgsexpressionfunction.cpp.

◆ variableHelpText()

QString QgsExpression::variableHelpText ( const QString & variableName )

static

Returns the help text for a specified variable.

Parameters

variableName name of variable

See also: helpText(); addVariableHelpText()

Since: QGIS 2.12

Definition at line 914 of file qgsexpression.cpp.

Friends And Related Function Documentation

◆ QgsOgcUtils

friend class QgsOgcUtils

friend

Definition at line 721 of file qgsexpression.h.

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

/build/qgis-3.22.4+99unstable/src/core/expression/qgsexpression.h
/build/qgis-3.22.4+99unstable/src/core/expression/qgsexpression.cpp
/build/qgis-3.22.4+99unstable/src/core/expression/qgsexpressionfunction.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Three Value Logic

Performance

Type conversion

Implicit sharing

Member Enumeration Documentation

◆ SpatialOperator

Constructor & Destructor Documentation

◆ QgsExpression() [1/3]

◆ QgsExpression() [2/3]

◆ QgsExpression() [3/3]

◆ ~QgsExpression()

Member Function Documentation

◆ addVariableHelpText()

◆ areaUnits()

◆ attemptReduceToInClause()

◆ BuiltinFunctions()

◆ checkExpression()

◆ cleanRegisteredFunctions()

◆ createFieldEqualityExpression()

◆ distanceUnits()

◆ dump()

◆ evalErrorString()

◆ evaluate() [1/2]

◆ evaluate() [2/2]

◆ evaluateToDouble()

◆ expression()

◆ expressionToLayerFieldIndex()

◆ findNodes()

◆ formatPreviewString()

◆ formatVariableHelp()

◆ functionCount()

◆ functionIndex()

◆ Functions()

◆ geomCalculator()

◆ group()

◆ hasEvalError()

◆ hasParserError()

◆ helpText()

◆ isField()

◆ isFieldEqualityExpression()

◆ isFunctionName()

◆ isValid()

◆ needsGeometry()

◆ nodes()

◆ operator QString()

◆ operator=()

◆ operator==()

◆ parserErrors()

◆ parserErrorString()

◆ prepare()

◆ quotedColumnRef()

◆ quotedString()

◆ quotedValue() [1/2]

◆ quotedValue() [2/2]

◆ referencedAttributeIndexes()

◆ referencedColumns()

◆ referencedFunctions()

◆ referencedVariables() [1/2]

◆ referencedVariables() [2/2]

◆ registerFunction()

◆ replaceExpressionText()

◆ rootNode()

◆ setAreaUnits()

◆ setDistanceUnits()

◆ setEvalErrorString()

◆ setExpression()

◆ setGeomCalculator()

◆ tags()

◆ unregisterFunction()

◆ variableHelpText()

Friends And Related Function Documentation

◆ QgsOgcUtils