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

#include <qgsexpression.h>

Inheritance diagram for QgsExpression:

Classes
class	Function
	A abstract base class for defining QgsExpression functions. More...

struct	Help

struct	HelpArg

struct	HelpExample

struct	HelpVariant

class	NamedNode
	Named node. More...

class	Node

class	NodeBinaryOperator

class	NodeColumnRef

class	NodeCondition

class	NodeFunction

class	NodeInOperator

class	NodeList

class	NodeLiteral

class	NodeUnaryOperator

class	Parameter
	Represents a single parameter passed to a function. More...

class	StaticFunction
	c++ helper class for defining QgsExpression functions. More...

class	Visitor
	Support for visitor pattern - algorithms dealing with the expressions may be implemented without modifying the Node classes. More...

class	WhenThen

Public Types
enum	BinaryOperator { boOr, boAnd, boEQ, boNE, boLE, boGE, boLT, boGT, boRegexp, boLike, boNotLike, boILike, boNotILike, boIs, boIsNot, boPlus, boMinus, boMul, boDiv, boIntDiv, boMod, boPow, boConcat }
	list of binary operators More...

typedef QVariant(*	FcnEval) (const QVariantList &values, const QgsFeature f, QgsExpression parent)

typedef QVariant(*	FcnEvalContext) (const QVariantList &values, const QgsExpressionContext context, QgsExpression parent)
	Function definition for evaluation against an expression context, using a list of values as parameters to the function. More...

typedef QgsInterval	Interval

enum	NodeType { ntUnaryOperator, ntBinaryOperator, ntInOperator, ntFunction, ntLiteral, ntColumnRef, ntCondition }

typedef QList< Parameter >	ParameterList
	List of parameters, used for function definition. More...

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

enum	UnaryOperator { uoNot, uoMinus }
	list of unary operators More...

typedef QList< WhenThen * >	WhenThenList

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

void	acceptVisitor (Visitor &v) const
	Entry function for the visitor pattern. More...

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

Q_DECL_DEPRECATED int	currentRowNumber ()
	Return the number used for $rownum special column. More...

QGis::UnitType	distanceUnits () const
	Returns the desired distance units for calculations involving geomCalculator(), eg "$length" and "$perimeter". More...

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

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

Q_DECL_DEPRECATED QVariant	evaluate (const QgsFeature *f)
	Evaluate the feature and return the result. More...

Q_DECL_DEPRECATED QVariant	evaluate (const QgsFeature &f)
	Evaluate the feature and return the result. More...

Q_DECL_DEPRECATED QVariant	evaluate (const QgsFeature *f, const QgsFields &fields)
	Evaluate the feature and return the result. More...

Q_DECL_DEPRECATED QVariant	evaluate (const QgsFeature &f, const QgsFields &fields)
	Evaluate the feature and return the result. 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
	Return the original, unmodified expression string. More...

QgsDistanceArea *	geomCalculator ()
	Return 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...

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

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

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

Q_DECL_DEPRECATED bool	prepare (const QgsFields &fields)
	Get the expression ready for evaluation - find out column indexes. More...

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

QStringList	referencedColumns () const
	Get list of columns referenced by the expression. More...

const Node *	rootNode () const
	Returns root node of the expression. Root node is null is parsing has failed. More...

double	scale ()

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

Q_DECL_DEPRECATED void	setCurrentRowNumber (int rowNumber)
	Set the number for $rownum special column. More...

void	setDistanceUnits (QGis::UnitType unit)
	Sets the desired distance units for calculations involving geomCalculator(), eg "$length" and "$perimeter". More...

void	setEvalErrorString (const QString &str)
	Set 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...

void	setScale (double scale)

Static Public Member Functions
static const QStringList &	BuiltinFunctions ()

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, const double fallbackValue)
	Attempts to evaluate a text string as an expression to a resultant double value. More...

static QString	formatPreviewString (const QVariant &value)
	Formats an expression result for friendly display to the user. More...

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

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

static const QList< Function * > &	Functions ()

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

static bool	hasSpecialColumn (const QString &name)
	Check whether a special column exists. 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 Q_DECL_DEPRECATED bool	isValid (const QString &text, const QgsFields &fields, QString &errorMessage)

static bool	isValid (const QString &text, const QgsExpressionContext *context, QString &errorMessage)
	Tests whether a string is a valid expression. 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 bool	registerFunction (Function *function, bool transferOwnership=false)
	Registers a function to the expression engine. More...

static Q_DECL_DEPRECATED QString	replaceExpressionText (const QString &action, const QgsFeature feat, QgsVectorLayer layer, const QMap< QString, QVariant > substitutionMap=nullptr, const QgsDistanceArea distanceArea=nullptr)
	This function currently replaces each expression between [% and %] in the string with the result of its evaluation on the feature passed as argument. More...

static QString	replaceExpressionText (const QString &action, const QgsExpressionContext context, const QMap< QString, QVariant > substitutionMap=nullptr, 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 Q_DECL_DEPRECATED void	setSpecialColumn (const QString &name, const QVariant &value)
	Assign a special column. More...

static Q_DECL_DEPRECATED QVariant	specialColumn (const QString &name)
	Return the value of the given special column or a null QVariant if undefined. More...

static QList< Function * >	specialColumns ()
	Returns a list of special Column definitions. More...

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

static Q_DECL_DEPRECATED void	unsetSpecialColumn (const QString &name)
	Unset a special column. More...

static QString	variableHelpText (const QString &variableName, bool showValue=true, const QVariant &value=QVariant())
	Returns the help text for a specified variable. More...

Static Public Attributes
static const char *	BinaryOperatorText []

static QStringList	gmBuiltinFunctions

static QList< Function * >	gmFunctions

static QList< Function * >	gmOwnedFunctions
	List of functions owned by the expression engine. More...

static const char *	UnaryOperatorText []

Protected Member Functions
void	detach ()
	Helper for implicit sharing. More...

void	initGeomCalculator ()

Static Protected Member Functions
static void	initFunctionHelp ()

static void	initVariableHelp ()

Protected Attributes
QgsExpressionPrivate *	d

Static Protected Attributes
static QHash< QString, Help >	gFunctionHelpTexts

static QHash< QString, QString >	gGroups

static QMap< QString, QString >	gmSpecialColumnGroups

static QMap< QString, QVariant >	gmSpecialColumns

static QHash< QString, QString >	gVariableHelpTexts

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: invalid 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 109 of file qgsexpression.h.

Member Typedef Documentation

◆ FcnEval

typedef QVariant( * QgsExpression::FcnEval) (const QVariantList &values, const QgsFeature *f, QgsExpression *parent)

Deprecated:: will be removed in QGIS 3.0

Definition at line 507 of file qgsexpression.h.

◆ FcnEvalContext

typedef QVariant( * QgsExpression::FcnEvalContext) (const QVariantList &values, const QgsExpressionContext *context, QgsExpression *parent)

Function definition for evaluation against an expression context, using a list of values as parameters to the function.

Definition at line 511 of file qgsexpression.h.

◆ ParameterList

typedef QList< Parameter > QgsExpression::ParameterList

List of parameters, used for function definition.

Definition at line 504 of file qgsexpression.h.

◆ WhenThenList

typedef QList<WhenThen*> QgsExpression::WhenThenList

Definition at line 1409 of file qgsexpression.h.

Member Enumeration Documentation

◆ BinaryOperator

enum QgsExpression::BinaryOperator

list of binary operators

Note: if any change is made here, the definition of QgsExpression::BinaryOperatorText[] must be adapted.

Enumerator
boOr
boAnd
boEQ
boNE
boLE
boGE
boLT
boGT
boRegexp
boLike
boNotLike
boILike
boNotILike
boIs
boIsNot
boPlus
boMinus
boMul
boDiv
boIntDiv
boMod
boPow
boConcat

Definition at line 409 of file qgsexpression.h.

◆ NodeType

enum QgsExpression::NodeType

Enumerator
ntUnaryOperator
ntBinaryOperator
ntInOperator
ntFunction
ntLiteral
ntColumnRef
ntCondition

Definition at line 909 of file qgsexpression.h.

◆ SpatialOperator

enum QgsExpression::SpatialOperator

Enumerator
soBbox
soIntersects
soContains
soCrosses
soEquals
soDisjoint
soOverlaps
soTouches
soWithin

Definition at line 443 of file qgsexpression.h.

◆ UnaryOperator

enum QgsExpression::UnaryOperator

list of unary operators

Note: if any change is made here, the definition of QgsExpression::UnaryOperatorText[] must be adapted.

Enumerator
uoNot
uoMinus

Definition at line 399 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 3684 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 3692 of file qgsexpression.cpp.

◆ QgsExpression() [3/3]

QgsExpression::QgsExpression ( )

Create an empty expression.

Note: Added in QGIS 2.18

Definition at line 3710 of file qgsexpression.cpp.

◆ ~QgsExpression()

QgsExpression::~QgsExpression ( )

Definition at line 3715 of file qgsexpression.cpp.

Member Function Documentation

◆ acceptVisitor()

void QgsExpression::acceptVisitor ( QgsExpression::Visitor & v ) const

Entry function for the visitor pattern.

Definition at line 3942 of file qgsexpression.cpp.

◆ areaUnits()

QgsUnitTypes::AreaUnit QgsExpression::areaUnits ( ) const

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

Note: areas are only converted when a geomCalculator() has been set; added in QGIS 2.14

See also: setAreaUnits(); distanceUnits()

Definition at line 3932 of file qgsexpression.cpp.

◆ BuiltinFunctions()

const QStringList & QgsExpression::BuiltinFunctions ( )

static

Definition at line 3222 of file qgsexpression.cpp.

◆ cleanRegisteredFunctions()

void QgsExpression::cleanRegisteredFunctions ( )

static

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

Note: added in QGIS 2.12

Definition at line 3214 of file qgsexpression.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 2.18

Definition at line 5327 of file qgsexpression.cpp.

◆ currentRowNumber()

int QgsExpression::currentRowNumber ( )

Return the number used for $rownum special column.

Deprecated:: use QgsExpressionContext to retrieve row number instead

Definition at line 3907 of file qgsexpression.cpp.

◆ detach()

void QgsExpression::detach ( )

protected

Helper for implicit sharing.

When called will create a new deep copy of this expression.

Note: not available in Python bindings

Definition at line 3779 of file qgsexpression.cpp.

◆ distanceUnits()

QGis::UnitType QgsExpression::distanceUnits ( ) const

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

Note: distances are only converted when a geomCalculator() has been set; added in QGIS 2.14

See also: setDistanceUnits(); areaUnits()

Definition at line 3922 of file qgsexpression.cpp.

◆ dump()

QString QgsExpression::dump ( ) const

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

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

Definition at line 3909 of file qgsexpression.cpp.

◆ evalErrorString()

QString QgsExpression::evalErrorString ( ) const

Returns evaluation error.

Definition at line 3892 of file qgsexpression.cpp.

◆ evaluate() [1/6]

QVariant QgsExpression::evaluate ( const QgsFeature * f )

Evaluate the feature and return the result.

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

Deprecated:: use evaluate( const QgsExpressionContext* context ) instead

Definition at line 3824 of file qgsexpression.cpp.

◆ evaluate() [2/6]

QVariant QgsExpression::evaluate ( const QgsFeature & f )

Evaluate the feature and return the result.

Note: prepare() should be called before calling this method; available in python bindings as evaluatePrepared

Deprecated:: use evaluate( const QgsExpressionContext* context ) instead

Definition at line 3837 of file qgsexpression.cpp.

◆ evaluate() [3/6]

QVariant QgsExpression::evaluate	(	const QgsFeature *	f,
		const QgsFields &	fields
	)

Evaluate the feature and return the result.

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

Deprecated:: use evaluate( const QgsExpressionContext* context ) instead

Definition at line 3844 of file qgsexpression.cpp.

◆ evaluate() [4/6]

QVariant QgsExpression::evaluate	(	const QgsFeature &	f,
		const QgsFields &	fields
	)

inline

Evaluate the feature and return the result.

Note: this method does not expect that prepare() has been called on this instance; not available in python bindings

Deprecated:: use evaluate( const QgsExpressionContext* context ) instead

Definition at line 3856 of file qgsexpression.cpp.

◆ evaluate() [5/6]

QVariant QgsExpression::evaluate ( )

Evaluate the feature and return the result.

Note: this method does not expect that prepare() has been called on this instance; added in QGIS 2.12

Definition at line 3863 of file qgsexpression.cpp.

◆ evaluate() [6/6]

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.; added in QGIS 2.12

Definition at line 3875 of file qgsexpression.cpp.

◆ evaluateToDouble()

double QgsExpression::evaluateToDouble	(	const QString &	text,
		const 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: added in QGIS 2.7; this method is inefficient for bulk evaluation of expressions, it is intended for one-off evaluations only.

Definition at line 4031 of file qgsexpression.cpp.

◆ expression()

QString QgsExpression::expression ( ) const

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

◆ formatPreviewString()

QString QgsExpression::formatPreviewString ( const QVariant & value )

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 (eg geometries and features).

Parameters

value expression result to format

Returns: formatted string, may contain HTML formatting characters

Note: added in QGIS 2.14

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

◆ functionIndex()

int QgsExpression::functionIndex ( const QString & name )

static

return index of the function in Functions array

Definition at line 3662 of file qgsexpression.cpp.

◆ Functions()

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

static

Definition at line 3282 of file qgsexpression.cpp.

◆ geomCalculator()

QgsDistanceArea * QgsExpression::geomCalculator ( )

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

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

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

◆ hasEvalError()

bool QgsExpression::hasEvalError ( ) const

Returns true if an error occurred when evaluating last input.

Definition at line 3887 of file qgsexpression.cpp.

◆ hasParserError()

bool QgsExpression::hasParserError ( ) const

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

Definition at line 3734 of file qgsexpression.cpp.

◆ hasSpecialColumn()

bool QgsExpression::hasSpecialColumn ( const QString & name )

static

Check whether a special column exists.

Note: added in 2.2

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

Definition at line 4967 of file qgsexpression.cpp.

◆ initFunctionHelp()

static void QgsExpression::initFunctionHelp ( )

staticprotected

Note: not available in Python bindings

◆ initGeomCalculator()

void QgsExpression::initGeomCalculator ( )

protected

Definition at line 3769 of file qgsexpression.cpp.

◆ initVariableHelp()

void QgsExpression::initVariableHelp ( )

staticprotected

Note: not available in Python bindings

Definition at line 5087 of file qgsexpression.cpp.

◆ isField()

bool QgsExpression::isField ( ) const

inline

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

Note: added in 2.9

Definition at line 266 of file qgsexpression.h.

◆ isFunctionName()

bool QgsExpression::isFunctionName ( const QString & name )

static

tells whether the identifier is a name of existing function

Definition at line 3657 of file qgsexpression.cpp.

◆ isValid() [1/3]

bool QgsExpression::isValid ( ) const

Checks if this expression is valid.

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

Note: Added in QGIS 2.18

Definition at line 3729 of file qgsexpression.cpp.

◆ isValid() [2/3]

bool QgsExpression::isValid	(	const QString &	text,
		const QgsFields &	fields,
		QString &	errorMessage
	)

static

Deprecated:: use QgsExpressionContext variant instead

Definition at line 3570 of file qgsexpression.cpp.

◆ isValid() [3/3]

bool QgsExpression::isValid	(	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

Note: added in QGIS 2.12

Definition at line 3576 of file qgsexpression.cpp.

◆ needsGeometry()

bool QgsExpression::needsGeometry ( ) const

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

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

Note: Added in QGIS 2.18

Definition at line 3722 of file qgsexpression.cpp.

◆ parserErrorString()

QString QgsExpression::parserErrorString ( ) const

Returns parser error.

Definition at line 3736 of file qgsexpression.cpp.

◆ prepare() [1/2]

bool QgsExpression::prepare ( const QgsFields & fields )

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

Deprecated:: use prepare( const QgsExpressionContext *context ) instead

Definition at line 3796 of file qgsexpression.cpp.

◆ prepare() [2/2]

bool QgsExpression::prepare ( const QgsExpressionContext * context )

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

Parameters

context context for preparing expression

Note: added in QGIS 2.12

Definition at line 3803 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 3616 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 3621 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

Note: added in QGIS 2.14

See also: quotedString(); quotedColumnRef()

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

Note: added in QGIS 2.14

See also: quotedString(); quotedColumnRef()

Definition at line 3635 of file qgsexpression.cpp.

◆ referencedColumns()

QStringList QgsExpression::referencedColumns ( ) const

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

TODO QGIS3: Return QSet<QString>

Definition at line 3738 of file qgsexpression.cpp.

◆ registerFunction()

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

static

Registers a function to the expression engine.

This is required to allow expressions to utilise 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 3185 of file qgsexpression.cpp.

◆ replaceExpressionText() [1/2]

QString QgsExpression::replaceExpressionText	(	const QString &	action,
		const QgsFeature *	feat,
		QgsVectorLayer *	layer,
		const QMap< QString, QVariant > *	substitutionMap = `nullptr`,
		const QgsDistanceArea *	distanceArea = `nullptr`
	)

static

This function currently replaces each expression between [% and %] in the string with the result of its evaluation on the feature passed as argument.

Additional substitutions can be passed through the substitutionMap parameter

Parameters

action
feat
layer
substitutionMap
distanceArea	optional QgsDistanceArea. If specified, the QgsDistanceArea is used for distance and area conversion

Deprecated:: use QgsExpressionContext variant instead

Definition at line 3948 of file qgsexpression.cpp.

◆ replaceExpressionText() [2/2]

QString QgsExpression::replaceExpressionText	(	const QString &	action,
		const QgsExpressionContext *	context,
		const QMap< QString, QVariant > *	substitutionMap = `nullptr`,
		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
context	expression context
substitutionMap
distanceArea	optional QgsDistanceArea. If specified, the QgsDistanceArea is used for distance and area conversion

Note: added in QGIS 2.12

Definition at line 3956 of file qgsexpression.cpp.

◆ rootNode()

const QgsExpression::Node * QgsExpression::rootNode ( ) const

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

Definition at line 5339 of file qgsexpression.cpp.

◆ scale()

double QgsExpression::scale ( )

Definition at line 3594 of file qgsexpression.cpp.

◆ setAreaUnits()

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

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

Note: areas are only converted when a geomCalculator() has been set; added in QGIS 2.14

See also: areaUnits(); setDistanceUnits()

Definition at line 3937 of file qgsexpression.cpp.

◆ setCurrentRowNumber()

void QgsExpression::setCurrentRowNumber ( int rowNumber )

Set the number for $rownum special column.

Deprecated:: use QgsExpressionContext to set row number instead

Definition at line 3902 of file qgsexpression.cpp.

◆ setDistanceUnits()

void QgsExpression::setDistanceUnits ( QGis::UnitType unit )

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

Note: distances are only converted when a geomCalculator() has been set; added in QGIS 2.14

See also: distanceUnits(); setAreaUnits()

Definition at line 3927 of file qgsexpression.cpp.

◆ setEvalErrorString()

void QgsExpression::setEvalErrorString ( const QString & str )

Set evaluation error (used internally by evaluation functions)

Definition at line 3897 of file qgsexpression.cpp.

◆ setExpression()

void QgsExpression::setExpression ( const QString & expression )

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

Note: Added in QGIS 2.18

Definition at line 3584 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). By default, no geometry calculator is set and all distance and area calculations are performed using simple cartesian methods (ie no ellipsoidal calculations).

See also: geomCalculator()

Definition at line 3791 of file qgsexpression.cpp.

◆ setScale()

void QgsExpression::setScale ( double scale )

Definition at line 3592 of file qgsexpression.cpp.

◆ setSpecialColumn()

void QgsExpression::setSpecialColumn	(	const QString &	name,
		const QVariant &	value
	)

static

Assign a special column.

Deprecated:: use global or project QgsExpressionContext variables instead

Definition at line 3527 of file qgsexpression.cpp.

◆ specialColumn()

QVariant QgsExpression::specialColumn ( const QString & name )

static

Return the value of the given special column or a null QVariant if undefined.

Deprecated:: use global or project QgsExpressionContext variables instead

Definition at line 3547 of file qgsexpression.cpp.

◆ specialColumns()

QList< QgsExpression::Function * > QgsExpression::specialColumns ( )

static

Returns a list of special Column definitions.

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

◆ unsetSpecialColumn()

void QgsExpression::unsetSpecialColumn ( const QString & name )

static

Unset a special column.

Deprecated:: use global or project QgsExpressionContext variables instead

Definition at line 3538 of file qgsexpression.cpp.

◆ variableHelpText()

QString QgsExpression::variableHelpText	(	const QString &	variableName,
		bool	showValue = `true`,
		const QVariant &	value = `QVariant()`
	)

static

Returns the help text for a specified variable.

Parameters

variableName	name 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()

Note: added in QGIS 2.12

Definition at line 5156 of file qgsexpression.cpp.

Friends And Related Function Documentation

◆ QgsOgcUtils

friend class QgsOgcUtils

friend

Definition at line 1598 of file qgsexpression.h.

Member Data Documentation

◆ BinaryOperatorText

const char * QgsExpression::BinaryOperatorText

static

Initial value:

=
{
  
  "OR", "AND",
  "=", "<>", "<=", ">=", "<", ">", "~", "LIKE", "NOT LIKE", "ILIKE", "NOT ILIKE", "IS", "IS NOT",
  "+", "-", "*", "/", "//", "%", "^",
  "||"
}

Note: not available in Python bindings

Definition at line 457 of file qgsexpression.h.

◆ d

QgsExpressionPrivate* QgsExpression::d

protected

Definition at line 1587 of file qgsexpression.h.

◆ gFunctionHelpTexts

QHash<QString, Help> QgsExpression::gFunctionHelpTexts

staticprotected

Definition at line 1589 of file qgsexpression.h.

◆ gGroups

QHash< QString, QString > QgsExpression::gGroups

staticprotected

Definition at line 1591 of file qgsexpression.h.

◆ gmBuiltinFunctions

QStringList QgsExpression::gmBuiltinFunctions

static

Note: not available in Python bindings

Definition at line 832 of file qgsexpression.h.

◆ gmFunctions

QList< QgsExpression::Function * > QgsExpression::gmFunctions

static

Note: not available in Python bindings

Definition at line 828 of file qgsexpression.h.

◆ gmOwnedFunctions

QList< QgsExpression::Function * > QgsExpression::gmOwnedFunctions

static

List of functions owned by the expression engine.

Note: not available in Python bindings

Definition at line 851 of file qgsexpression.h.

◆ gmSpecialColumnGroups

QMap< QString, QString > QgsExpression::gmSpecialColumnGroups

staticprotected

Definition at line 1504 of file qgsexpression.h.

◆ gmSpecialColumns

QMap< QString, QVariant > QgsExpression::gmSpecialColumns

staticprotected

Definition at line 1503 of file qgsexpression.h.

◆ gVariableHelpTexts

QHash< QString, QString > QgsExpression::gVariableHelpTexts

staticprotected

Definition at line 1590 of file qgsexpression.h.

◆ UnaryOperatorText

const char * QgsExpression::UnaryOperatorText

static

Initial value:

=
{
  
  "NOT", "-"
}

Note: not available in Python bindings

Definition at line 460 of file qgsexpression.h.

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

/tmp/buildd/qgis-2.18.21+99unstable/src/core/qgsexpression.h
/tmp/buildd/qgis-2.18.21+99unstable/src/core/qgsexpression.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Friends

Detailed Description

Three Value Logic

Performance

Type conversion

Implicit sharing

Member Typedef Documentation

◆ FcnEval

◆ FcnEvalContext

◆ ParameterList

◆ WhenThenList

Member Enumeration Documentation

◆ BinaryOperator

◆ NodeType

◆ SpatialOperator

◆ UnaryOperator

Constructor & Destructor Documentation

◆ QgsExpression() [1/3]

◆ QgsExpression() [2/3]

◆ QgsExpression() [3/3]

◆ ~QgsExpression()

Member Function Documentation

◆ acceptVisitor()

◆ areaUnits()

◆ BuiltinFunctions()

◆ cleanRegisteredFunctions()

◆ createFieldEqualityExpression()

◆ currentRowNumber()

◆ detach()

◆ distanceUnits()

◆ dump()

◆ evalErrorString()

◆ evaluate() [1/6]

◆ evaluate() [2/6]

◆ evaluate() [3/6]

◆ evaluate() [4/6]

◆ evaluate() [5/6]

◆ evaluate() [6/6]

◆ evaluateToDouble()

◆ expression()

◆ formatPreviewString()

◆ functionCount()

◆ functionIndex()

◆ Functions()

◆ geomCalculator()

◆ group()

◆ hasEvalError()

◆ hasParserError()

◆ hasSpecialColumn()

◆ helptext()

◆ initFunctionHelp()

◆ initGeomCalculator()

◆ initVariableHelp()

◆ isField()

◆ isFunctionName()

◆ isValid() [1/3]

◆ isValid() [2/3]

◆ isValid() [3/3]

◆ needsGeometry()

◆ operator=()

◆ operator==()

◆ parserErrorString()

◆ prepare() [1/2]

◆ prepare() [2/2]

◆ quotedColumnRef()

◆ quotedString()

◆ quotedValue() [1/2]

◆ quotedValue() [2/2]

◆ referencedColumns()

◆ registerFunction()

◆ replaceExpressionText() [1/2]