QGIS API Documentation  2.9.0-Master
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups Pages
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 | List of all members
QgsExpression Class Reference

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

#include <qgsexpression.h>

Inheritance diagram for QgsExpression:
Inheritance graph
[legend]

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
int currentRowNumber ()
 Return the number used for $rownum special column.
QString dump () const
 Return the expression string that represents this QgsExpression.
QString evalErrorString () const
 Returns evaluation error.
QVariant evaluate (const QgsFeature *f=NULL)
 Evaluate the feature and return the result.
QVariant evaluate (const QgsFeature &f)
 Evaluate the feature and return the result.
QVariant evaluate (const QgsFeature *f, const QgsFields &fields)
 Evaluate the feature and return the result.
QVariant evaluate (const QgsFeature &f, const QgsFields &fields)
 Evaluate the feature and return the result.
const QString expression () const
 Alias for dump()
QgsDistanceAreageomCalculator ()
 Return calculator used for distance and area calculations (used by internal functions)
bool hasEvalError () const
 Returns true if an error occurred when evaluating last input.
bool hasParserError () const
 Returns true if an error occurred when parsing the input expression.
bool isField () const
 Checks whether an expression consists only of a single field reference.
bool needsGeometry () const
 Returns true if the expression uses feature geometry for some computation.
QString parserErrorString () const
 Returns parser error.
bool prepare (const QgsFields &fields)
 Get the expression ready for evaluation - find out column indexes.
QStringList referencedColumns () const
 Get list of columns referenced by the expression.
const NoderootNode () const
 Returns root node of the expression. Root node is null is parsing has failed.
double scale ()
void setCurrentRowNumber (int rowNumber)
 Set the number for $rownum special column.
void setEvalErrorString (QString str)
 Set evaluation error (used internally by evaluation functions)
void setGeomCalculator (const QgsDistanceArea &calc)
 Sets the geometry calculator used in evaluation of expressions,.
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.
static int functionCount ()
 Returns the number of functions defined in the parser.
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.
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)
static QString quotedString (QString text)
 return quoted string (in single quotes)
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.
static void setSpecialColumn (const QString &name, QVariant value)
 Assign a special column.
static QVariant specialColumn (const QString &name)
 Return the value of the given special column or a null QVariant if undefined.
static QList< Function * > specialColumns ()
 Returns a list of special Column definitions.
static bool unregisterFunction (QString name)
static void unsetSpecialColumn (const QString &name)
 Unset a special column.

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.
void initGeomCalculator ()

Static Protected Member Functions

static void initFunctionHelp ()

Protected Attributes

QgsDistanceAreamCalc
QString mEvalErrorString
QString mExp
QString mParserErrorString
NodemRootNode
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:

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.

Definition at line 625 of file qgsexpression.h.

Member Enumeration Documentation

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.

Enumerator:
ntUnaryOperator 
ntBinaryOperator 
ntInOperator 
ntFunction 
ntLiteral 
ntColumnRef 
ntCondition 

Definition at line 389 of file qgsexpression.h.

Enumerator:
soBbox 
soIntersects 
soContains 
soCrosses 
soEquals 
soDisjoint 
soOverlaps 
soTouches 
soWithin 

Definition at line 264 of file qgsexpression.h.

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

QgsExpression::~QgsExpression ( )

Definition at line 1981 of file qgsexpression.cpp.

QgsExpression::QgsExpression ( )
inlineprotected

Used by QgsOgcUtils to create an empty.

Definition at line 674 of file qgsexpression.h.

Member Function Documentation

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

entry function for the visitor pattern

Definition at line 2077 of file qgsexpression.cpp.

const QStringList & QgsExpression::BuiltinFunctions ( )
static

Definition at line 1660 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 2069 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 2046 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 2058 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
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
added in QGIS 2.7

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

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

Definition at line 1947 of file qgsexpression.cpp.

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

Definition at line 1703 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 2848 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 1873 of file qgsexpression.cpp.

QString QgsExpression::helptext ( QString  name)
static

Definition at line 2840 of file qgsexpression.cpp.

void QgsExpression::initFunctionHelp ( )
staticprotected

Definition at line 6 of file qgsexpression_texts.cpp.

void QgsExpression::initGeomCalculator ( )
protected

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

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

Definition at line 1908 of file qgsexpression.cpp.

bool QgsExpression::needsGeometry ( ) const

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

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

QString QgsExpression::quotedColumnRef ( QString  name)
static

return quoted column reference (in double quotes)

Definition at line 1928 of file qgsexpression.cpp.

QString QgsExpression::quotedString ( QString  text)
static

return quoted string (in single quotes)

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

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

Definition at line 1629 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
distanceAreaoptional QgsDistanceArea. If specified, the QgsDistanceArea is used for distance and area conversion

Definition at line 2083 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 2028 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 1837 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 1857 of file qgsexpression.cpp.

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

Returns a list of special Column definitions.

Definition at line 1916 of file qgsexpression.cpp.

bool QgsExpression::unregisterFunction ( QString  name)
static

Definition at line 1640 of file qgsexpression.cpp.

void QgsExpression::unsetSpecialColumn ( const QString &  name)
static

Unset a special column.

Definition at line 1848 of file qgsexpression.cpp.

Friends And Related Function Documentation

friend class QgsOgcUtils
friend

Definition at line 697 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 692 of file qgsexpression.h.

QHash< QString, QString > QgsExpression::gGroups
staticprotected

Definition at line 693 of file qgsexpression.h.

QStringList QgsExpression::gmBuiltinFunctions
static

Definition at line 358 of file qgsexpression.h.

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

Definition at line 355 of file qgsexpression.h.

QMap< QString, QString > QgsExpression::gmSpecialColumnGroups
staticprotected

Definition at line 690 of file qgsexpression.h.

QMap< QString, QVariant > QgsExpression::gmSpecialColumns
staticprotected

Definition at line 689 of file qgsexpression.h.

QgsDistanceArea* QgsExpression::mCalc
protected

Definition at line 687 of file qgsexpression.h.

QString QgsExpression::mEvalErrorString
protected

Definition at line 681 of file qgsexpression.h.

QString QgsExpression::mExp
protected

Definition at line 685 of file qgsexpression.h.

QString QgsExpression::mParserErrorString
protected

Definition at line 680 of file qgsexpression.h.

Node* QgsExpression::mRootNode
protected

Definition at line 678 of file qgsexpression.h.

int QgsExpression::mRowNumber
protected

Definition at line 683 of file qgsexpression.h.

double QgsExpression::mScale
protected

Definition at line 684 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: