QGIS API Documentation  3.4.15-Madeira (e83d02e274)
Classes | Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Friends | List of all members
QgsExpression Class Reference

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...
 
QgsDistanceAreageomCalculator ()
 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...
 
QgsExpressionoperator= (const QgsExpression &other)
 Create a copy of this expression. More...
 
bool operator== (const QgsExpression &other) const
 Compares two expressions. More...
 
QList< QgsExpression::ParserErrorparserErrors () 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 QgsExpressionNoderootNode () 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

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
textstring to test
contextoptional expression context
errorMessagewill 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
fieldNamethe name of the field
valuethe 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
contextcontext 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
texttext to evaluate as expression
fallbackValuevalue 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
valueexpression result to format
htmlOutputset 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
descriptiontranslated description of variable
showValueset to true to include current value of variable in help text
valuecurrent 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
groupuntranslated 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
namefunction 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
contextcontext 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
valuevalue 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
valuevalue to convert to a string representation
typevalue 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
textThe 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
functionfunction to register
transferOwnershipset 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
actionThe source string in which placeholders should be replaced.
contextExpression context
distanceAreaOptional 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
calcgeometry 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
namefunction 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
variableNamename 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: