QGIS API Documentation  3.37.0-Master (a5b4d9743e8)
Classes | Public Types | Public Member Functions | Static Public Member Functions | 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 ()
 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 ()
 
Qgis::AreaUnit areaUnits () const
 Returns the desired areal units for calculations involving geomCalculator(), e.g., "$area". More...
 
Qgis::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 the root node of the expression. More...
 
void setAreaUnits (Qgis::AreaUnit unit)
 Sets the desired areal units for calculations involving geomCalculator(), e.g., "$area". More...
 
void setDistanceUnits (Qgis::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, QVariant::Type fieldType=QVariant::Type::Invalid)
 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 PRIVATE 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 QString quoteFieldExpression (const QString &expression, const QgsVectorLayer *layer)
 Validate if the expression is a field in the layer and ensure it is quoted. 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 QgsExpressionNodeFunction
 
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
Class for parsing and evaluation of expressions (formerly called "search strings").

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

Member Enumeration Documentation

◆ SpatialOperator

Enumerator
soBbox 
soIntersects 
soContains 
soCrosses 
soEquals 
soDisjoint 
soOverlaps 
soTouches 
soWithin 

Definition at line 584 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 170 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 178 of file qgsexpression.cpp.

◆ QgsExpression() [3/3]

QgsExpression::QgsExpression ( )

Create an empty expression.

Definition at line 204 of file qgsexpression.cpp.

◆ ~QgsExpression()

QgsExpression::~QgsExpression ( )

Definition at line 209 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
namevariable name
descriptionthe 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 933 of file qgsexpression.cpp.

◆ areaUnits()

Qgis::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()

Definition at line 445 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
expressionsexpressions to test
resultwill 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 1187 of file qgsexpression.cpp.

◆ BuiltinFunctions()

const QStringList & QgsExpression::BuiltinFunctions ( )
static

Definition at line 9304 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
textstring to test
contextoptional expression context
errorMessagewill be filled with any error message from the validation
Returns
true if string is a valid expression

Definition at line 49 of file qgsexpression.cpp.

◆ cleanRegisteredFunctions()

void QgsExpression::cleanRegisteredFunctions ( )
static

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

Definition at line 9298 of file qgsexpressionfunction.cpp.

◆ createFieldEqualityExpression()

QString QgsExpression::createFieldEqualityExpression ( const QString &  fieldName,
const QVariant &  value,
QVariant::Type  fieldType = QVariant::Type::Invalid 
)
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
fieldTypethe type of the field on the left side used to quote the value. If not given, the value type is used instead
Returns
the expression to evaluate field equality

Definition at line 1149 of file qgsexpression.cpp.

◆ distanceUnits()

Qgis::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()

Definition at line 435 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 414 of file qgsexpression.cpp.

◆ evalErrorString()

QString QgsExpression::evalErrorString ( ) const

Returns evaluation error.

Definition at line 404 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

Definition at line 371 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
contextcontext for evaluating expression
Note
prepare() should be called before calling this method.

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

Definition at line 531 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 66 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 1388 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 373 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
valueexpression result to format
htmlOutputset to true to allow HTML formatting, or false for plain text output
maximumPreviewLengthdefine the maximum character length of the preview
Returns
formatted string, may contain HTML formatting characters if htmlOutput is true

Definition at line 1001 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
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()

Definition at line 949 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 164 of file qgsexpression.cpp.

◆ functionIndex()

int QgsExpression::functionIndex ( const QString &  name)
static

Returns index of the function in Functions array.

Definition at line 133 of file qgsexpression.cpp.

◆ Functions()

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

Definition at line 8078 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 422 of file qgsexpression.cpp.

◆ group()

QString QgsExpression::group ( const QString &  group)
static

Returns the translated name for a function group.

Parameters
groupuntranslated group name

Definition at line 968 of file qgsexpression.cpp.

◆ hasEvalError()

bool QgsExpression::hasEvalError ( ) const

Returns true if an error occurred when evaluating last input.

Definition at line 399 of file qgsexpression.cpp.

◆ hasParserError()

bool QgsExpression::hasParserError ( ) const

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

Definition at line 226 of file qgsexpression.cpp.

◆ helpText()

QString QgsExpression::helpText ( QString  name)
static

Returns the help text for a specified function.

Parameters
namefunction name
See also
variableHelpText()
formatVariableHelp()

Definition at line 559 of file qgsexpression.cpp.

◆ isField()

bool QgsExpression::isField ( ) const

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

See also
expressionToLayerFieldIndex()

Definition at line 1383 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
expressionexpression to test
fieldwill be set to the field name if the expression is a field equality expression
valuewill 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 1163 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 128 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.

Definition at line 221 of file qgsexpression.cpp.

◆ needsGeometry()

bool QgsExpression::needsGeometry ( ) const

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

Definition at line 291 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 1425 of file qgsexpression.cpp.

◆ operator QString()

QgsExpression::operator QString ( ) const

Automatically convert this expression to a string where requested.

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

Definition at line 216 of file qgsexpression.cpp.

◆ parserErrors()

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

Returns parser error details including location of error.

Definition at line 236 of file qgsexpression.cpp.

◆ parserErrorString()

QString QgsExpression::parserErrorString ( ) const

Returns parser error.

Definition at line 231 of file qgsexpression.cpp.

◆ prepare()

bool QgsExpression::prepare ( const QgsExpressionContext context)

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

Parameters
contextcontext for preparing expression

Definition at line 348 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 74 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 79 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
valuevalue to convert to a string representation
See also
quotedString()
quotedColumnRef()

Definition at line 88 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
valuevalue to convert to a string representation
typevalue type
See also
quotedString()
quotedColumnRef()

Definition at line 93 of file qgsexpression.cpp.

◆ quoteFieldExpression()

QString QgsExpression::quoteFieldExpression ( const QString &  expression,
const QgsVectorLayer layer 
)
static

Validate if the expression is a field in the layer and ensure it is quoted.

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 quoted field.

Returns
the expression if not a field or quotes are not required, otherwise returns a quoted field.
See also
expressionToLayerFieldIndex()
Since
QGIS 3.24

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

Definition at line 265 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 241 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 257 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().

Definition at line 249 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
textThe source string in which variables should be searched.
Since
QGIS 3.2

Definition at line 510 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
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 9264 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
actionThe source string in which placeholders should be replaced.
contextExpression context
distanceAreaOptional QgsDistanceArea. If specified, the QgsDistanceArea is used for distance and area conversion

Definition at line 455 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 1378 of file qgsexpression.cpp.

◆ setAreaUnits()

void QgsExpression::setAreaUnits ( Qgis::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()

Definition at line 450 of file qgsexpression.cpp.

◆ setDistanceUnits()

void QgsExpression::setDistanceUnits ( Qgis::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()

Definition at line 440 of file qgsexpression.cpp.

◆ setEvalErrorString()

void QgsExpression::setEvalErrorString ( const QString &  str)

Sets evaluation error (used internally by evaluation functions)

Definition at line 409 of file qgsexpression.cpp.

◆ setExpression()

void QgsExpression::setExpression ( const QString &  expression)

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

Definition at line 57 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
calcgeometry calculator. Ownership is not transferred. Set to nullptr to force Cartesian calculations.
See also
geomCalculator()

Definition at line 339 of file qgsexpression.cpp.

◆ tags()

QStringList QgsExpression::tags ( const QString &  name)
static

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

Parameters
namefunction name
Since
QGIS 3.12

Definition at line 694 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
namefunction name
See also
registerFunction

Definition at line 9280 of file qgsexpressionfunction.cpp.

◆ variableHelpText()

QString QgsExpression::variableHelpText ( const QString &  variableName)
static

Returns the help text for a specified variable.

Parameters
variableNamename of variable
See also
helpText()
addVariableHelpText()

Definition at line 943 of file qgsexpression.cpp.

Friends And Related Function Documentation

◆ QgsExpressionNodeFunction

friend class QgsExpressionNodeFunction
friend

Definition at line 804 of file qgsexpression.h.

◆ QgsOgcUtils

friend class QgsOgcUtils
friend

Definition at line 808 of file qgsexpression.h.


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