QGIS API Documentation  2.7.0-Master
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules 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>

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, boMod,
  boPow, boConcat
}
 
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 }
 
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...
 
QgsDistanceAreageomCalculator ()
 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 needsGeometry ()
 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 ()
 Get list of columns referenced by the expression. More...
 
const NoderootNode () 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 int functionCount ()
 Returns the number of functions defined in the parser. More...
 
static int functionIndex (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 ()
 
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 87 of file qgsexpression.h.

Member Typedef Documentation

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

Definition at line 249 of file qgsexpression.h.

Definition at line 577 of file qgsexpression.h.

Member Enumeration Documentation

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

Definition at line 201 of file qgsexpression.h.

Enumerator
ntUnaryOperator 
ntBinaryOperator 
ntInOperator 
ntFunction 
ntLiteral 
ntColumnRef 
ntCondition 

Definition at line 342 of file qgsexpression.h.

Enumerator
soBbox 
soIntersects 
soContains 
soCrosses 
soEquals 
soDisjoint 
soOverlaps 
soTouches 
soWithin 

Definition at line 233 of file qgsexpression.h.

Enumerator
uoNot 
uoMinus 

Definition at line 196 of file qgsexpression.h.

Constructor & Destructor Documentation

QgsExpression::QgsExpression ( const QString &  expr)

Definition at line 1876 of file qgsexpression.cpp.

QgsExpression::~QgsExpression ( )

Definition at line 1888 of file qgsexpression.cpp.

QgsExpression::QgsExpression ( )
inlineprotected

Definition at line 624 of file qgsexpression.h.

Member Function Documentation

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

entry function for the visitor pattern

Definition at line 1984 of file qgsexpression.cpp.

const QStringList & QgsExpression::BuiltinFunctions ( )
static

Definition at line 1586 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 1976 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 1953 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 1965 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.

const QString QgsExpression::expression ( ) const
inline

Alias for dump()

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

int QgsExpression::functionIndex ( QString  name)
static

Definition at line 1859 of file qgsexpression.cpp.

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

Definition at line 1618 of file qgsexpression.cpp.

QgsDistanceArea* QgsExpression::geomCalculator ( )
inline

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

Definition at line 172 of file qgsexpression.h.

QString QgsExpression::group ( QString  group)
static

Definition at line 2710 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 94 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 1785 of file qgsexpression.cpp.

QString QgsExpression::helptext ( QString  name)
static

Definition at line 2702 of file qgsexpression.cpp.

void QgsExpression::initFunctionHelp ( )
staticprotected

Definition at line 6 of file qgsexpression_texts.cpp.

void QgsExpression::initGeomCalculator ( )
protected

Definition at line 1925 of file qgsexpression.cpp.

bool QgsExpression::isFunctionName ( QString  name)
static

Definition at line 1854 of file qgsexpression.cpp.

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

Definition at line 1820 of file qgsexpression.cpp.

bool QgsExpression::needsGeometry ( )

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

Definition at line 1918 of file qgsexpression.cpp.

QString QgsExpression::parserErrorString ( ) const
inline

Returns parser error.

Definition at line 96 of file qgsexpression.h.

bool QgsExpression::prepare ( const QgsFields fields)

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

Definition at line 1941 of file qgsexpression.cpp.

QString QgsExpression::quotedColumnRef ( QString  name)
static

return quoted column reference (in double quotes)

Definition at line 1840 of file qgsexpression.cpp.

QString QgsExpression::quotedString ( QString  text)
static

return quoted string (in single quotes)

Definition at line 1845 of file qgsexpression.cpp.

QStringList QgsExpression::referencedColumns ( )

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

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

Definition at line 1555 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 1990 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 101 of file qgsexpression.h.

double QgsExpression::scale ( )
inline

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

void QgsExpression::setScale ( double  scale)
inline

Definition at line 160 of file qgsexpression.h.

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

Assign a special column.

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

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

Returns a list of special Column definitions.

Definition at line 1828 of file qgsexpression.cpp.

bool QgsExpression::unregisterFunction ( QString  name)
static

Definition at line 1566 of file qgsexpression.cpp.

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

Unset a special column.

Definition at line 1760 of file qgsexpression.cpp.

Friends And Related Function Documentation

friend class QgsOgcUtils
friend

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

QHash< QString, QString > QgsExpression::gFunctionHelpTexts
staticprotected

Definition at line 645 of file qgsexpression.h.

QHash< QString, QString > QgsExpression::gGroups
staticprotected

Definition at line 646 of file qgsexpression.h.

QStringList QgsExpression::gmBuiltinFunctions
static

Definition at line 311 of file qgsexpression.h.

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

Definition at line 309 of file qgsexpression.h.

QMap< QString, QString > QgsExpression::gmSpecialColumnGroups
staticprotected

Definition at line 638 of file qgsexpression.h.

QMap< QString, QVariant > QgsExpression::gmSpecialColumns
staticprotected

Definition at line 637 of file qgsexpression.h.

QgsDistanceArea* QgsExpression::mCalc
protected

Definition at line 640 of file qgsexpression.h.

QString QgsExpression::mEvalErrorString
protected

Definition at line 631 of file qgsexpression.h.

QString QgsExpression::mExp
protected

Definition at line 635 of file qgsexpression.h.

QString QgsExpression::mParserErrorString
protected

Definition at line 630 of file qgsexpression.h.

Node* QgsExpression::mRootNode
protected

Definition at line 628 of file qgsexpression.h.

int QgsExpression::mRowNumber
protected

Definition at line 633 of file qgsexpression.h.

double QgsExpression::mScale
protected

Definition at line 634 of file qgsexpression.h.

const char * QgsExpression::UnaryOperatorText
static
Initial value:
=
{
"NOT", "-"
}

Definition at line 247 of file qgsexpression.h.


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