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 (const QString &expr)
	Creates a new expression based on the provided string. More...

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

	QgsExpression ()
	Create an empty expression. 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 root node of the expression. Root node is null is parsing has failed. 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 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 QString	formatPreviewString (const QVariant &value, bool htmlOutput=true)
	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	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 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...

Static Public Attributes
static QStringList	sBuiltinFunctions

static QList< QgsExpressionFunction * >	sFunctions

static QList< QgsExpressionFunction * >	sOwnedFunctions
	List of functions owned by the expression engine. 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:

QgsExpression exp("gid*2 > 10 and type not in ('D','F')");
if (exp.hasParserError())
{
  // show error message with parserErrorString() and exit
}
QVariant 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 113 of file qgsexpression.h.

Member Enumeration Documentation

enum QgsExpression::SpatialOperator

Enumerator
soBbox
soIntersects
soContains
soCrosses
soEquals
soDisjoint
soOverlaps
soTouches
soWithin

Definition at line 470 of file qgsexpression.h.

Constructor & Destructor Documentation

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 197 of file qgsexpression.cpp.

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 205 of file qgsexpression.cpp.

QgsExpression::QgsExpression ( )

Create an empty expression.

Since: QGIS 3.0

Definition at line 228 of file qgsexpression.cpp.

QgsExpression::~QgsExpression ( )

Definition at line 233 of file qgsexpression.cpp.

Member Function Documentation

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 460 of file qgsexpression.cpp.

const QStringList & QgsExpression::BuiltinFunctions ( )

static

Definition at line 79 of file qgsexpression.cpp.

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 91 of file qgsexpression.cpp.

void QgsExpression::cleanRegisteredFunctions ( )

static

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

Since: QGIS 2.12

Definition at line 71 of file qgsexpression.cpp.

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 1020 of file qgsexpression.cpp.

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 450 of file qgsexpression.cpp.

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 437 of file qgsexpression.cpp.

QString QgsExpression::evalErrorString ( ) const

Returns evaluation error.

Definition at line 427 of file qgsexpression.cpp.

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 394 of file qgsexpression.cpp.

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 406 of file qgsexpression.cpp.

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 543 of file qgsexpression.cpp.

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 108 of file qgsexpression.cpp.

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 285 of file qgsexpression.h.

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

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

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

Since: QGIS 2.14

Definition at line 899 of file qgsexpression.cpp.

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 847 of file qgsexpression.cpp.

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 191 of file qgsexpression.cpp.

int QgsExpression::functionIndex ( const QString & name )

static

Returns index of the function in Functions array.

Definition at line 174 of file qgsexpression.cpp.

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

static

Definition at line 4435 of file qgsexpressionfunction.cpp.

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 445 of file qgsexpression.cpp.

QString QgsExpression::group ( const QString & group )

static

Returns the translated name for a function group.

Parameters

group untranslated group name

Definition at line 868 of file qgsexpression.cpp.

bool QgsExpression::hasEvalError ( ) const

Returns true if an error occurred when evaluating last input.

Definition at line 422 of file qgsexpression.cpp.

bool QgsExpression::hasParserError ( ) const

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

Definition at line 250 of file qgsexpression.cpp.

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 573 of file qgsexpression.cpp.

bool QgsExpression::isField ( ) const

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

Since: QGIS 2.9

Definition at line 1037 of file qgsexpression.cpp.

bool QgsExpression::isFunctionName ( const QString & name )

static

tells whether the identifier is a name of existing function

Definition at line 169 of file qgsexpression.cpp.

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 245 of file qgsexpression.cpp.

bool QgsExpression::needsGeometry ( ) const

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

Definition at line 310 of file qgsexpression.cpp.

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 1042 of file qgsexpression.cpp.

QgsExpression::operator QString ( ) const

Automatically convert this expression to a string where requested.

Since: QGIS 3.0

Definition at line 223 of file qgsexpression.cpp.

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 211 of file qgsexpression.cpp.

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 240 of file qgsexpression.cpp.

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

Returns parser error details including location of error.

Since: QGIS 3.0

Definition at line 260 of file qgsexpression.cpp.

QString QgsExpression::parserErrorString ( ) const

Returns parser error.

Definition at line 255 of file qgsexpression.cpp.

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 371 of file qgsexpression.cpp.

QString QgsExpression::quotedColumnRef ( QString name )

static

Returns a quoted column reference (in double quotes)

See also: quotedString(); quotedValue()

Definition at line 116 of file qgsexpression.cpp.

QString QgsExpression::quotedString ( QString text )

static

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

See also: quotedValue(); quotedColumnRef()

Definition at line 121 of file qgsexpression.cpp.

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 130 of file qgsexpression.cpp.

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 135 of file qgsexpression.cpp.

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

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

Since: QGIS 3.0

Definition at line 289 of file qgsexpression.cpp.

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.

See also: referencedAttributeIndexes()

Definition at line 265 of file qgsexpression.cpp.

QSet< QString > QgsExpression::referencedFunctions ( ) const

Returns a list of the names of all functions which are used in this expression.

Since: QGIS 3.2

Definition at line 281 of file qgsexpression.cpp.

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.

Since: QGIS 3.0

Definition at line 273 of file qgsexpression.cpp.

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 521 of file qgsexpression.cpp.

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 42 of file qgsexpression.cpp.

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 470 of file qgsexpression.cpp.

const QgsExpressionNode * QgsExpression::rootNode ( ) const

Returns root node of the expression. Root node is null is parsing has failed.

Definition at line 1032 of file qgsexpression.cpp.

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 465 of file qgsexpression.cpp.

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 455 of file qgsexpression.cpp.

void QgsExpression::setEvalErrorString ( const QString & str )

Sets evaluation error (used internally by evaluation functions)

Definition at line 432 of file qgsexpression.cpp.

void QgsExpression::setExpression ( const QString & expression )

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

Since: QGIS 3.0

Definition at line 99 of file qgsexpression.cpp.

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 a nullptr to force Cartesian calculations.

See also: geomCalculator()

Definition at line 362 of file qgsexpression.cpp.

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 55 of file qgsexpression.cpp.

QString QgsExpression::variableHelpText ( const QString & variableName )

static

Returns the help text for a specified variable.

Parameters

variableName name of variable

See also: helpText()

Since: QGIS 2.12

Definition at line 841 of file qgsexpression.cpp.

Friends And Related Function Documentation

friend class QgsOgcUtils

friend

Definition at line 725 of file qgsexpression.h.

Member Data Documentation

QStringList QgsExpression::sBuiltinFunctions

static

Note: not available in Python bindings

Definition at line 488 of file qgsexpression.h.

QList< QgsExpressionFunction * > QgsExpression::sFunctions

static

Note: not available in Python bindings

Definition at line 484 of file qgsexpression.h.

QList< QgsExpressionFunction * > QgsExpression::sOwnedFunctions

static

List of functions owned by the expression engine.

Note: not available in Python bindings

Definition at line 511 of file qgsexpression.h.

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

/build/qgis-3.4.15+24xenial/src/core/expression/qgsexpression.h
/build/qgis-3.4.15+24xenial/src/core/expression/qgsexpression.cpp
/build/qgis-3.4.15+24xenial/src/core/expression/qgsexpressionfunction.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Friends

Detailed Description

Three Value Logic

Performance

Type conversion

Implicit sharing

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation