Quantum GIS API Documentation  1.8
Classes | Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Protected Attributes
QgsExpression Class Reference

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

#include <qgsexpression.h>

Collaboration diagram for QgsExpression:
Collaboration graph
[legend]

List of all members.

Classes

struct  FunctionDef
class  Node
class  NodeBinaryOperator
class  NodeColumnRef
class  NodeCondition
class  NodeFunction
class  NodeInOperator
class  NodeList
class  NodeLiteral
class  NodeUnaryOperator
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
}
typedef QVariant(* FcnEval )(const QVariantList &values, 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.
QString parserErrorString () const
 Returns parser error.
bool prepare (const QgsFieldMap &fields)
 Get the expression ready for evaluation - find out column indexes.
QStringList referencedColumns ()
 Get list of columns referenced by the expression.
bool needsGeometry ()
 Returns true if the expression uses feature geometry for some computation.
QVariant evaluate (QgsFeature *f=NULL)
 Evaluate the feature and return the result.
QVariant evaluate (QgsFeature *f, const QgsFieldMap &fields)
 Evaluate the feature and return the result.
bool hasEvalError () const
 Returns true if an error occurred when evaluating last input.
QString evalErrorString () const
 Returns evaluation error.
void setEvalErrorString (QString str)
 Set evaluation error (used internally by evaluation functions)
void setCurrentRowNumber (int rowNumber)
 Set the number for $rownum special column.
int currentRowNumber ()
 Return the number used for $rownum special column.
QString dump () const
 Return the parsed expression as a string - useful for debugging.
QgsDistanceAreageomCalculator ()
 Return calculator used for distance and area calculations (used by internal functions)
void acceptVisitor (Visitor &v)
 entry function for the visitor pattern
void toOgcFilter (QDomDocument &doc, QDomElement &element) const

Static Public Member Functions

static const QList< FunctionDef > & BuiltinFunctions ()
static bool isFunctionName (QString name)
static int functionIndex (QString name)
static int functionCount ()
 Returns the number of functions defined in the parser.
static QString quotedColumnRef (QString name)
 return quoted column reference (in double quotes)
static QString quotedString (QString text)
 return quoted string (in single quotes)
static QgsExpressioncreateFromOgcFilter (QDomElement &element)

Static Public Attributes

static const char * BinaryOperatorText []
static const char * UnaryOperatorText []
static const char * BinaryOgcOperatorText []
static const char * UnaryOgcOperatorText []
static QList< FunctionDefgmBuiltinFunctions

Protected Member Functions

 QgsExpression ()
void initGeomCalculator ()

Protected Attributes

QString mExpression
NodemRootNode
QString mParserErrorString
QString mEvalErrorString
int mRowNumber
QgsDistanceAreamCalc

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

Definition at line 82 of file qgsexpression.h.


Member Typedef Documentation

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

Definition at line 176 of file qgsexpression.h.

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

Enumerator:
uoNot 
uoMinus 

Definition at line 132 of file qgsexpression.h.


Constructor & Destructor Documentation

QgsExpression::QgsExpression ( const QString &  expr)

Definition at line 481 of file qgsexpression.cpp.

References mExpression, mParserErrorString, mRootNode, and parseExpression().

Definition at line 492 of file qgsexpression.cpp.

References mCalc, and mRootNode.

QgsExpression::QgsExpression ( ) [inline, protected]

Definition at line 472 of file qgsexpression.h.

Referenced by createFromOgcFilter().


Member Function Documentation

entry function for the visitor pattern

Definition at line 623 of file qgsexpression.cpp.

References QgsExpression::Node::accept(), and mRootNode.

QgsExpression * QgsExpression::createFromOgcFilter ( QDomElement &  element) [static]

Return the number used for $rownum special column.

Definition at line 121 of file qgsexpression.h.

Referenced by fcnRowNumber().

QString QgsExpression::dump ( ) const

Return the parsed expression as a string - useful for debugging.

Definition at line 572 of file qgsexpression.cpp.

References QgsExpression::Node::dump(), and mRootNode.

Referenced by QgsRuleBasedRendererV2::Rule::createFromSld(), and QgsSymbolLayerV2Utils::functionFromSldElement().

QString QgsExpression::evalErrorString ( ) const [inline]
QVariant QgsExpression::evaluate ( QgsFeature f = NULL)
QVariant QgsExpression::evaluate ( QgsFeature f,
const QgsFieldMap 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 561 of file qgsexpression.cpp.

References evaluate(), and prepare().

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

References BuiltinFunctions().

Referenced by functionIndex(), and QgsExpressionBuilderWidget::QgsExpressionBuilderWidget().

int QgsExpression::functionIndex ( QString  name) [static]

Definition at line 464 of file qgsexpression.cpp.

References BuiltinFunctions(), and functionCount().

Referenced by isFunctionName().

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

Definition at line 128 of file qgsexpression.h.

Referenced by fcnGeomArea(), fcnGeomLength(), and fcnGeomPerimeter().

bool QgsExpression::hasEvalError ( ) const [inline]
bool QgsExpression::hasParserError ( ) const [inline]
void QgsExpression::initGeomCalculator ( ) [protected]
bool QgsExpression::isFunctionName ( QString  name) [static]

Definition at line 459 of file qgsexpression.cpp.

References functionIndex().

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

Definition at line 521 of file qgsexpression.cpp.

References mRootNode, and QgsExpression::Node::needsGeometry().

Referenced by QgsSearchQueryBuilder::countRecords(), and QgsExpressionBuilderWidget::on_txtExpressionString_textChanged().

QString QgsExpression::parserErrorString ( ) const [inline]
bool QgsExpression::prepare ( const QgsFieldMap fields)

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

Definition at line 537 of file qgsexpression.cpp.

References mEvalErrorString, mRootNode, and QgsExpression::Node::prepare().

Referenced by QgsSearchQueryBuilder::countRecords(), and evaluate().

static QString QgsExpression::quotedColumnRef ( QString  name) [inline, static]

return quoted column reference (in double quotes)

Definition at line 211 of file qgsexpression.h.

Referenced by QgsSearchQueryBuilder::populateFields(), QgsRuleBasedRendererV2::refineRuleCategories(), and QgsRuleBasedRendererV2::refineRuleRanges().

static QString QgsExpression::quotedString ( QString  text) [inline, static]

return quoted string (in single quotes)

Definition at line 213 of file qgsexpression.h.

Referenced by QgsRuleBasedRendererV2::refineRuleCategories().

Get list of columns referenced by the expression.

Definition at line 498 of file qgsexpression.cpp.

References mRootNode, and QgsExpression::Node::referencedColumns().

Referenced by QgsPalLabeling::prepareLayer().

void QgsExpression::setCurrentRowNumber ( int  rowNumber) [inline]

Set the number for $rownum special column.

Definition at line 119 of file qgsexpression.h.

void QgsExpression::setEvalErrorString ( QString  str) [inline]

Set evaluation error (used internally by evaluation functions)

Definition at line 116 of file qgsexpression.h.

Referenced by fcnRegexpReplace(), getDoubleValue(), getIntValue(), getTVLValue(), and pointAt().

void QgsExpression::toOgcFilter ( QDomDocument &  doc,
QDomElement &  element 
) const

Member Data Documentation

const char * QgsExpression::BinaryOgcOperatorText [static]
Initial value:
{
  "Or", "And",
  "PropertyIsEqualTo", "PropertyIsNotEqualTo",
  "PropertyIsGreaterThanOrEqualTo", "PropertyIsLessThanOrEqualTo",
  "PropertyIsLessThan", "PropertyIsGreaterThan",
  "", "PropertyIsLike", "", "", "",
  "Add", "Sub", "Mul", "Div", "", "",
  ""
}

Definition at line 173 of file qgsexpression.h.

Referenced by QgsExpression::Node::createFromOgcFilter(), QgsExpression::NodeBinaryOperator::createFromOgcFilter(), and QgsExpression::NodeBinaryOperator::toOgcFilter().

const char * QgsExpression::BinaryOperatorText [static]
Initial value:
{
  "OR", "AND",
  "=", "<>", "<=", ">=", "<", ">", "~", "LIKE", "NOT LIKE", "ILIKE", "NOT ILIKE", "IS", "IS NOT",
  "+", "-", "*", "/", "%", "^",
  "||"
}

Definition at line 170 of file qgsexpression.h.

Referenced by QgsExpression::NodeBinaryOperator::dump(), and QgsExpression::NodeBinaryOperator::toOgcFilter().

Definition at line 197 of file qgsexpression.h.

Referenced by BuiltinFunctions().

Definition at line 483 of file qgsexpression.h.

Referenced by initGeomCalculator(), and ~QgsExpression().

QString QgsExpression::mEvalErrorString [protected]

Definition at line 478 of file qgsexpression.h.

Referenced by evaluate(), prepare(), and QgsExpression::NodeColumnRef::prepare().

QString QgsExpression::mExpression [protected]

Definition at line 474 of file qgsexpression.h.

Referenced by QgsExpression().

QString QgsExpression::mParserErrorString [protected]

Definition at line 477 of file qgsexpression.h.

Referenced by createFromOgcFilter(), and QgsExpression().

int QgsExpression::mRowNumber [protected]

Definition at line 480 of file qgsexpression.h.

const char * QgsExpression::UnaryOgcOperatorText [static]
Initial value:
{
  "Not", ""
}

Definition at line 174 of file qgsexpression.h.

Referenced by QgsExpression::Node::createFromOgcFilter(), and QgsExpression::NodeUnaryOperator::createFromOgcFilter().

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

Definition at line 171 of file qgsexpression.h.

Referenced by QgsExpression::NodeUnaryOperator::dump(), and QgsExpression::NodeUnaryOperator::toOgcFilter().


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines