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

class	Interval

class	Node

class	NodeBinaryOperator

class	NodeColumnRef

class	NodeCondition

class	NodeFunction

class	NodeInOperator

class	NodeList

class	NodeLiteral

class	NodeUnaryOperator

class	StaticFunction

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)

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

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)

	~QgsExpression ()

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

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

QString	dump () const
	Return the expression string that represents this QgsExpression. More...

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

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

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

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

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

const QString	expression () const
	Alias for dump() More...

QgsDistanceArea *	geomCalculator ()
	Return calculator used for distance and area calculations (used by internal functions) 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	needsGeometry () const
	Returns true if the expression uses feature geometry for some computation. More...

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

bool	prepare (const QgsFields &fields)
	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	setCurrentRowNumber (int rowNumber)
	Set the number for $rownum special column. More...

void	setEvalErrorString (QString str)
	Set evaluation error (used internally by evaluation functions) More...

void	setGeomCalculator (const QgsDistanceArea &calc)
	Sets the geometry calculator used in evaluation of expressions,. More...

void	setScale (double scale)

Static Public Member Functions
static const QStringList &	BuiltinFunctions ()

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 int	functionCount ()
	Returns the number of functions defined in the parser. More...

static int	functionIndex (const QString &name)

static const QList< Function * > &	Functions ()

static QString	group (QString group)

static bool	hasSpecialColumn (const QString &name)
	Check whether a special column exists. More...

static QString	helptext (QString name)

static bool	isFunctionName (QString name)

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

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

static QString	quotedString (QString text)
	return quoted string (in single quotes) More...

static bool	registerFunction (Function *function)

static QString	replaceExpressionText (const QString &action, const QgsFeature feat, QgsVectorLayer layer, const QMap< QString, QVariant > substitutionMap=0, const QgsDistanceArea distanceArea=0)
	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 void	setSpecialColumn (const QString &name, QVariant value)
	Assign a special column. More...

static 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 (QString name)

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

Static Public Attributes
static const char *	BinaryOperatorText []

static QStringList	gmBuiltinFunctions

static QList< Function * >	gmFunctions

static const char *	UnaryOperatorText []

Protected Member Functions
	QgsExpression ()
	Used by QgsOgcUtils to create an empty. More...

void	initGeomCalculator ()

Static Protected Member Functions
static void	initFunctionHelp ()

Protected Attributes
QgsDistanceArea *	mCalc

QString	mEvalErrorString

QString	mExp

QString	mParserErrorString

Node *	mRootNode

int	mRowNumber

double	mScale

Static Protected Attributes
static QHash< QString, QString >	gFunctionHelpTexts

static QHash< QString, QString >	gGroups

static QMap< QString, QString >	gmSpecialColumnGroups

static QMap< QString, QVariant >	gmSpecialColumns

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
}

Possible QVariant value types:

invalid (null)
int
double
string
geometry

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.

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 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 toint, toreal, tostring 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.

Arithmetic operators do integer arithmetics if both operands are integer. That is 2+2 yields integer 4, but 2.0+2 returns real number 4.0. There are also two versions of division and modulo operators: 1.0/2 returns 0.5 while 1/2 returns 0.

Definition at line 86 of file qgsexpression.h.

Member Typedef Documentation

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

Definition at line 280 of file qgsexpression.h.

typedef QList<WhenThen*> QgsExpression::WhenThenList

Definition at line 661 of file qgsexpression.h.

Member Enumeration Documentation

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

enum QgsExpression::NodeType

Enumerator
ntUnaryOperator
ntBinaryOperator
ntInOperator
ntFunction
ntLiteral
ntColumnRef
ntCondition

Definition at line 424 of file qgsexpression.h.

enum QgsExpression::SpatialOperator

Enumerator
soBbox
soIntersects
soContains
soCrosses
soEquals
soDisjoint
soOverlaps
soTouches
soWithin

Definition at line 264 of file qgsexpression.h.

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

Constructor & Destructor Documentation

QgsExpression::QgsExpression ( const QString & expr )

Definition at line 1980 of file qgsexpression.cpp.

QgsExpression::~QgsExpression ( )

Definition at line 1992 of file qgsexpression.cpp.

QgsExpression::QgsExpression ( )

inlineprotected

Used by QgsOgcUtils to create an empty.

Definition at line 710 of file qgsexpression.h.

Member Function Documentation

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

entry function for the visitor pattern

Definition at line 2088 of file qgsexpression.cpp.

const QStringList & QgsExpression::BuiltinFunctions ( )

static

Definition at line 1671 of file qgsexpression.cpp.

int QgsExpression::currentRowNumber ( )

inline

Return the number used for $rownum special column.

Definition at line 146 of file qgsexpression.h.

QString QgsExpression::dump ( ) const

Return the expression string that represents this QgsExpression.

Definition at line 2080 of file qgsexpression.cpp.

QString QgsExpression::evalErrorString ( ) const

inline

Returns evaluation error.

Definition at line 139 of file qgsexpression.h.

QVariant QgsExpression::evaluate ( const QgsFeature * f = NULL )

Evaluate the feature and return the result.

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

Definition at line 2057 of file qgsexpression.cpp.

QVariant QgsExpression::evaluate ( const QgsFeature & f )

inline

Evaluate the feature and return the result.

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

Definition at line 125 of file qgsexpression.h.

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

Definition at line 2069 of file qgsexpression.cpp.

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

Definition at line 134 of file qgsexpression.h.

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

Definition at line 2174 of file qgsexpression.cpp.

const QString QgsExpression::expression ( ) const

inline

Alias for dump()

Definition at line 170 of file qgsexpression.h.

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

int QgsExpression::functionIndex ( const QString & name )

static

Definition at line 1958 of file qgsexpression.cpp.

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

static

Definition at line 1714 of file qgsexpression.cpp.

QgsDistanceArea* QgsExpression::geomCalculator ( )

inline

Return calculator used for distance and area calculations (used by internal functions)

Definition at line 183 of file qgsexpression.h.

QString QgsExpression::group ( QString group )

static

Definition at line 2904 of file qgsexpression.cpp.

bool QgsExpression::hasEvalError ( ) const

inline

Returns true if an error occurred when evaluating last input.

Definition at line 137 of file qgsexpression.h.

bool QgsExpression::hasParserError ( ) const

inline

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

Definition at line 93 of file qgsexpression.h.

bool QgsExpression::hasSpecialColumn ( const QString & name )

static

Check whether a special column exists.

Note: added in 2.2

Definition at line 1884 of file qgsexpression.cpp.

QString QgsExpression::helptext ( QString name )

static

Definition at line 2896 of file qgsexpression.cpp.

void QgsExpression::initFunctionHelp ( )

staticprotected

Definition at line 6 of file qgsexpression_texts.cpp.

void QgsExpression::initGeomCalculator ( )

protected

Definition at line 2029 of file qgsexpression.cpp.

bool QgsExpression::isField ( ) const

inline

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

Note: added in 2.9

Definition at line 161 of file qgsexpression.h.

bool QgsExpression::isFunctionName ( QString name )

static

Definition at line 1953 of file qgsexpression.cpp.

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

static

Definition at line 1919 of file qgsexpression.cpp.

bool QgsExpression::needsGeometry ( ) const

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

Definition at line 2022 of file qgsexpression.cpp.

QString QgsExpression::parserErrorString ( ) const

inline

Returns parser error.

Definition at line 95 of file qgsexpression.h.

bool QgsExpression::prepare ( const QgsFields & fields )

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

Definition at line 2045 of file qgsexpression.cpp.

QString QgsExpression::quotedColumnRef ( QString name )

static

return quoted column reference (in double quotes)

Definition at line 1939 of file qgsexpression.cpp.

QString QgsExpression::quotedString ( QString text )

static

return quoted string (in single quotes)

Definition at line 1944 of file qgsexpression.cpp.

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.

Definition at line 1998 of file qgsexpression.cpp.

bool QgsExpression::registerFunction ( QgsExpression::Function * function )

static

Definition at line 1640 of file qgsexpression.cpp.

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

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

Definition at line 2094 of file qgsexpression.cpp.

const Node* QgsExpression::rootNode ( ) const

inline

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

Definition at line 100 of file qgsexpression.h.

double QgsExpression::scale ( )

inline

Definition at line 167 of file qgsexpression.h.

void QgsExpression::setCurrentRowNumber ( int rowNumber )

inline

Set the number for $rownum special column.

Definition at line 144 of file qgsexpression.h.

void QgsExpression::setEvalErrorString ( QString str )

inline

Set evaluation error (used internally by evaluation functions)

Definition at line 141 of file qgsexpression.h.

void QgsExpression::setGeomCalculator ( const QgsDistanceArea & calc )

Sets the geometry calculator used in evaluation of expressions,.

Definition at line 2039 of file qgsexpression.cpp.

void QgsExpression::setScale ( double scale )

inline

Definition at line 165 of file qgsexpression.h.

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

static

Assign a special column.

Definition at line 1848 of file qgsexpression.cpp.

QVariant QgsExpression::specialColumn ( const QString & name )

static

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

Definition at line 1868 of file qgsexpression.cpp.

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

static

Returns a list of special Column definitions.

Definition at line 1927 of file qgsexpression.cpp.

bool QgsExpression::unregisterFunction ( QString name )

static

Definition at line 1651 of file qgsexpression.cpp.

void QgsExpression::unsetSpecialColumn ( const QString & name )

static

Unset a special column.

Definition at line 1859 of file qgsexpression.cpp.

Friends And Related Function Documentation

friend class QgsOgcUtils

friend

Definition at line 733 of file qgsexpression.h.

Member Data Documentation

const char * QgsExpression::BinaryOperatorText

static

Initial value:

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

Definition at line 277 of file qgsexpression.h.

QHash< QString, QString > QgsExpression::gFunctionHelpTexts

staticprotected

Definition at line 728 of file qgsexpression.h.

QHash< QString, QString > QgsExpression::gGroups

staticprotected

Definition at line 729 of file qgsexpression.h.

QStringList QgsExpression::gmBuiltinFunctions

static

Definition at line 393 of file qgsexpression.h.

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

static

Definition at line 390 of file qgsexpression.h.

QMap< QString, QString > QgsExpression::gmSpecialColumnGroups

staticprotected

Definition at line 726 of file qgsexpression.h.

QMap< QString, QVariant > QgsExpression::gmSpecialColumns

staticprotected

Definition at line 725 of file qgsexpression.h.

QgsDistanceArea* QgsExpression::mCalc

protected

Definition at line 723 of file qgsexpression.h.

QString QgsExpression::mEvalErrorString

protected

Definition at line 717 of file qgsexpression.h.

QString QgsExpression::mExp

protected

Definition at line 721 of file qgsexpression.h.

QString QgsExpression::mParserErrorString

protected

Definition at line 716 of file qgsexpression.h.

Node* QgsExpression::mRootNode

protected

Definition at line 714 of file qgsexpression.h.

int QgsExpression::mRowNumber

protected

Definition at line 719 of file qgsexpression.h.

double QgsExpression::mScale

protected

Definition at line 720 of file qgsexpression.h.

const char * QgsExpression::UnaryOperatorText

static

Initial value:

=
{
  
  "NOT", "-"
}

Definition at line 278 of file qgsexpression.h.

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

/tmp/buildd/qgis-2.10.1+git20150822+dd4475c+20trusty/src/core/qgsexpression.h
/tmp/buildd/qgis-2.10.1+git20150822+dd4475c+20trusty/src/core/qgsexpression.cpp
/tmp/buildd/qgis-2.10.1+git20150822+dd4475c+20trusty/src/core/qgsexpression_texts.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

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation