QGIS API Documentation  2.5.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  UnaryOperator { uoNot, uoMinus }
 
enum  BinaryOperator {
  boOr, boAnd, boEQ, boNE,
  boLE, boGE, boLT, boGT,
  boRegexp, boLike, boNotLike, boILike,
  boNotILike, boIs, boIsNot, boPlus,
  boMinus, boMul, boDiv, boMod,
  boPow, boConcat
}
 
enum  SpatialOperator {
  soBbox, soIntersects, soContains, soCrosses,
  soEquals, soDisjoint, soOverlaps, soTouches,
  soWithin
}
 
enum  NodeType {
  ntUnaryOperator, ntBinaryOperator, ntInOperator, ntFunction,
  ntLiteral, ntColumnRef, ntCondition
}
 
typedef QVariant(* FcnEval )(const QVariantList &values, const QgsFeature *f, QgsExpression *parent)
 
typedef QList< WhenThen * > WhenThenList
 

Public Member Functions

 QgsExpression (const QString &expr)
 
 ~QgsExpression ()
 
bool hasParserError () const
 Returns true if an error occurred when parsing the input expression. More...
 
QString parserErrorString () const
 Returns parser error. More...
 
const NoderootNode () const
 Returns root node of the expression. Root node is null is parsing has failed. 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...
 
bool needsGeometry ()
 Returns true if the expression uses feature geometry for some computation. 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...
 
bool hasEvalError () const
 Returns true if an error occurred when evaluating last input. More...
 
QString evalErrorString () const
 Returns evaluation error. More...
 
void setEvalErrorString (QString str)
 Set evaluation error (used internally by evaluation functions) More...
 
void setCurrentRowNumber (int rowNumber)
 Set the number for $rownum special column. More...
 
int currentRowNumber ()
 Return the number used for $rownum special column. More...
 
void setScale (double scale)
 
double scale ()
 
const QString expression () const
 Alias for dump() More...
 
QString dump () const
 Return the expression string that represents this QgsExpression. More...
 
QgsDistanceAreageomCalculator ()
 Return calculator used for distance and area calculations (used by internal functions) More...
 
void setGeomCalculator (const QgsDistanceArea &calc)
 Sets the geometry calculator used in evaluation of expressions,. More...
 
void acceptVisitor (Visitor &v) const
 entry function for the visitor pattern More...
 

Static Public Member Functions

static void setSpecialColumn (const QString &name, QVariant value)
 Assign a special column. More...
 
static void unsetSpecialColumn (const QString &name)
 Unset 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 bool hasSpecialColumn (const QString &name)
 Check whether a special column exists. More...
 
static bool isValid (const QString &text, const QgsFields &fields, QString &errorMessage)
 
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 const QList< Function * > & Functions ()
 
static const QStringList & BuiltinFunctions ()
 
static bool registerFunction (Function *function)
 
static bool unregisterFunction (QString name)
 
static bool isFunctionName (QString name)
 
static int functionIndex (QString name)
 
static int functionCount ()
 Returns the number of functions defined in the parser. More...
 
static QList< Function * > specialColumns ()
 Returns a list of special Column definitions. More...
 
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 QString helptext (QString name)
 
static QString group (QString group)
 

Static Public Attributes

static const char * BinaryOperatorText []
 
static const char * UnaryOperatorText []
 
static QList< Function * > gmFunctions
 
static QStringList gmBuiltinFunctions
 

Protected Member Functions

 QgsExpression ()
 
void initGeomCalculator ()
 

Static Protected Member Functions

static void initFunctionHelp ()
 

Protected Attributes

NodemRootNode
 
QString mParserErrorString
 
QString mEvalErrorString
 
int mRowNumber
 
double mScale
 
QString mExp
 
QgsDistanceAreamCalc
 

Static Protected Attributes

static QMap< QString, QVariant > gmSpecialColumns
 
static QMap< QString, QString > gmSpecialColumnGroups
 
static QHash< QString, QString > gFunctionHelpTexts
 
static QHash< QString, QString > gGroups
 

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.

Note
added in 2.0

Member Typedef Documentation

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

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 
Enumerator
ntUnaryOperator 
ntBinaryOperator 
ntInOperator 
ntFunction 
ntLiteral 
ntColumnRef 
ntCondition 
Enumerator
soBbox 
soIntersects 
soContains 
soCrosses 
soEquals 
soDisjoint 
soOverlaps 
soTouches 
soWithin 
Enumerator
uoNot 
uoMinus 

Constructor & Destructor Documentation

QgsExpression::QgsExpression ( const QString &  expr)
QgsExpression::~QgsExpression ( )
QgsExpression::QgsExpression ( )
inlineprotected

Member Function Documentation

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

entry function for the visitor pattern

const QStringList & QgsExpression::BuiltinFunctions ( )
static
int QgsExpression::currentRowNumber ( )
inline

Return the number used for $rownum special column.

QString QgsExpression::dump ( ) const

Return the expression string that represents this QgsExpression.

QString QgsExpression::evalErrorString ( ) const
inline

Returns evaluation error.

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

Evaluate the feature and return the result.

Note
prepare() should be called before calling this method
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
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
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
const QString QgsExpression::expression ( ) const
inline

Alias for dump()

int QgsExpression::functionCount ( )
static

Returns the number of functions defined in the parser.

Returns
The number of function defined in the parser.
int QgsExpression::functionIndex ( QString  name)
static
const QList< QgsExpression::Function * > & QgsExpression::Functions ( )
static
QgsDistanceArea* QgsExpression::geomCalculator ( )
inline

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

QString QgsExpression::group ( QString  group)
static
bool QgsExpression::hasEvalError ( ) const
inline

Returns true if an error occurred when evaluating last input.

bool QgsExpression::hasParserError ( ) const
inline

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

bool QgsExpression::hasSpecialColumn ( const QString &  name)
static

Check whether a special column exists.

Note
added in 2.2
QString QgsExpression::helptext ( QString  name)
static
void QgsExpression::initFunctionHelp ( )
staticprotected
void QgsExpression::initGeomCalculator ( )
protected
bool QgsExpression::isFunctionName ( QString  name)
static
bool QgsExpression::isValid ( const QString &  text,
const QgsFields fields,
QString &  errorMessage 
)
static
bool QgsExpression::needsGeometry ( )

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

QString QgsExpression::parserErrorString ( ) const
inline

Returns parser error.

bool QgsExpression::prepare ( const QgsFields fields)

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

QString QgsExpression::quotedColumnRef ( QString  name)
static

return quoted column reference (in double quotes)

QString QgsExpression::quotedString ( QString  text)
static

return quoted string (in single quotes)

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.
bool QgsExpression::registerFunction ( QgsExpression::Function function)
static
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
const Node* QgsExpression::rootNode ( ) const
inline

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

double QgsExpression::scale ( )
inline
void QgsExpression::setCurrentRowNumber ( int  rowNumber)
inline

Set the number for $rownum special column.

void QgsExpression::setEvalErrorString ( QString  str)
inline

Set evaluation error (used internally by evaluation functions)

void QgsExpression::setGeomCalculator ( const QgsDistanceArea calc)

Sets the geometry calculator used in evaluation of expressions,.

void QgsExpression::setScale ( double  scale)
inline
void QgsExpression::setSpecialColumn ( const QString &  name,
QVariant  value 
)
static

Assign a special column.

QVariant QgsExpression::specialColumn ( const QString &  name)
static

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

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

Returns a list of special Column definitions.

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

Unset a special column.

Friends And Related Function Documentation

friend class QgsOgcUtils
friend

Member Data Documentation

const char * QgsExpression::BinaryOperatorText
static
Initial value:
=
{
"OR", "AND",
"=", "<>", "<=", ">=", "<", ">", "~", "LIKE", "NOT LIKE", "ILIKE", "NOT ILIKE", "IS", "IS NOT",
"+", "-", "*", "/", "%", "^",
"||"
}
QHash< QString, QString > QgsExpression::gFunctionHelpTexts
staticprotected
QHash< QString, QString > QgsExpression::gGroups
staticprotected
QStringList QgsExpression::gmBuiltinFunctions
static
QList< QgsExpression::Function * > QgsExpression::gmFunctions
static
QMap< QString, QString > QgsExpression::gmSpecialColumnGroups
staticprotected
QMap< QString, QVariant > QgsExpression::gmSpecialColumns
staticprotected
QgsDistanceArea* QgsExpression::mCalc
protected
QString QgsExpression::mEvalErrorString
protected
QString QgsExpression::mExp
protected
QString QgsExpression::mParserErrorString
protected
Node* QgsExpression::mRootNode
protected
int QgsExpression::mRowNumber
protected
double QgsExpression::mScale
protected
const char * QgsExpression::UnaryOperatorText
static
Initial value:
=
{
"NOT", "-"
}

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