QGIS API Documentation  2.2.0-Valmiera
 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>

Collaboration diagram for QgsExpression:
Collaboration 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  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.
QString parserErrorString () const
 Returns parser error.
const NoderootNode () const
 Returns root node of the expression. Root node is null is parsing has failed.
bool prepare (const QgsFields &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 (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.
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.
void setScale (double scale)
int scale ()
const QString expression () const
 Return the expression string that was given when created.
QString dump () const
 Return the expression string that represents this QgsExpression.
QgsDistanceAreageomCalculator ()
 Return calculator used for distance and area calculations (used by internal functions)
void setGeomCalculator (const QgsDistanceArea &calc)
 Sets the geometry calculator used in evaluation of expressions,.
void acceptVisitor (Visitor &v) const
 entry function for the visitor pattern

Static Public Member Functions

static void setSpecialColumn (const QString &name, QVariant value)
 Assign a special column.
static void unsetSpecialColumn (const QString &name)
 Unset a special column.
static QVariant specialColumn (const QString &name)
 Return the value of the given special column or a null QVariant if undefined.
static bool hasSpecialColumn (const QString &name)
 Check whether a special column exists.
static QString replaceExpressionText (const QString &action, const QgsFeature *feat, QgsVectorLayer *layer, const QMap< QString, QVariant > *substitutionMap=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 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.
static QList< Function * > specialColumns ()
 Returns a list of special Column definitions.
static QString quotedColumnRef (QString name)
 return quoted column reference (in double quotes)
static QString quotedString (QString text)
 return quoted string (in single quotes)
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 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

Definition at line 89 of file qgsexpression.h.

Member Typedef Documentation

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

Definition at line 235 of file qgsexpression.h.

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

Enumerator:
ntUnaryOperator 
ntBinaryOperator 
ntInOperator 
ntFunction 
ntLiteral 
ntColumnRef 
ntCondition 

Definition at line 324 of file qgsexpression.h.

Enumerator:
soBbox 
soIntersects 
soContains 
soCrosses 
soEquals 
soDisjoint 
soOverlaps 
soTouches 
soWithin 

Definition at line 219 of file qgsexpression.h.

Enumerator:
uoNot 
uoMinus 

Definition at line 182 of file qgsexpression.h.

Constructor & Destructor Documentation

QgsExpression::QgsExpression ( const QString &  expr)

Definition at line 1640 of file qgsexpression.cpp.

References mParserErrorString, mRootNode, and parseExpression().

QgsExpression::~QgsExpression ( )

Definition at line 1652 of file qgsexpression.cpp.

References mCalc, and mRootNode.

QgsExpression::QgsExpression ( )
inlineprotected

Definition at line 604 of file qgsexpression.h.

Member Function Documentation

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

entry function for the visitor pattern

Definition at line 1747 of file qgsexpression.cpp.

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

const QStringList & QgsExpression::BuiltinFunctions ( )
static

Definition at line 1404 of file qgsexpression.cpp.

References gmBuiltinFunctions.

Referenced by unregisterFunction().

int QgsExpression::currentRowNumber ( )
inline

Return the number used for $rownum special column.

Definition at line 142 of file qgsexpression.h.

Referenced by fcnRowNumber().

QString QgsExpression::dump ( ) const

Return the expression string that represents this QgsExpression.

Definition at line 1739 of file qgsexpression.cpp.

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

Referenced by QgsOgcUtils::expressionFromOgcFilter().

QString QgsExpression::evalErrorString ( ) const
inline
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 1716 of file qgsexpression.cpp.

References QgsExpression::Node::eval(), mEvalErrorString, mRootNode, and tr.

Referenced by QgsFeatureRequest::acceptFeature(), QgsSVGFillSymbolLayer::applyDataDefinedSettings(), QgsLinePatternFillSymbolLayer::applyDataDefinedSettings(), QgsPointPatternFillSymbolLayer::applyDataDefinedSettings(), QgsSimpleFillSymbolLayerV2::applyDataDefinedSymbology(), QgsSimpleLineSymbolLayerV2::applyDataDefinedSymbology(), QgsGradientFillSymbolLayerV2::applyDataDefinedSymbology(), QgsSearchQueryBuilder::countRecords(), QgsAttributeEditor::createAttributeEditor(), QgsFeatureListModel::data(), QgsPalLayerSettings::dataDefinedValue(), QgsSimpleLineSymbolLayerV2::dxfColor(), QgsSimpleFillSymbolLayerV2::dxfColor(), QgsSimpleLineSymbolLayerV2::dxfWidth(), QgsSimpleFillSymbolLayerV2::dxfWidth(), QgsImageFillSymbolLayer::dxfWidth(), evaluate(), QgsAttributeAction::expandAction(), QgsVectorLayerFeatureIterator::fetchNextChangedAttributeFeature(), QgsAttributeDialog::init(), QgsAttributeTableModel::loadAttributes(), QgsMarkerSymbolLayerV2::markerOffset(), QgsAbstractFeatureIterator::nextFeatureFilterExpression(), QgsExpressionSelectionDialog::on_mActionAddToSelection_triggered(), QgsExpressionSelectionDialog::on_mActionRemoveFromSelection_triggered(), QgsExpressionSelectionDialog::on_mActionSelect_triggered(), QgsExpressionSelectionDialog::on_mActionSelectInstersect_triggered(), QgsExpressionBuilderWidget::on_txtExpressionString_textChanged(), QgsEllipseSymbolLayerV2::preparePath(), QgsPalLayerSettings::registerFeature(), QgsEllipseSymbolLayerV2::renderPoint(), QgsSimpleMarkerSymbolLayerV2::renderPoint(), QgsSvgMarkerSymbolLayerV2::renderPoint(), QgsMarkerLineSymbolLayerV2::renderPolyline(), QgsMarkerLineSymbolLayerV2::renderPolylineInterval(), replaceExpressionText(), QgsEllipseSymbolLayerV2::writeDxf(), QgsSimpleMarkerSymbolLayerV2::writeDxf(), and QgsSvgMarkerSymbolLayerV2::writeDxf().

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

References evaluate().

Referenced by evaluate().

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

References evaluate(), and prepare().

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

Definition at line 130 of file qgsexpression.h.

References evaluate().

Referenced by evaluate().

const QString QgsExpression::expression ( ) const
inline
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 1634 of file qgsexpression.cpp.

References Functions().

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

int QgsExpression::functionIndex ( QString  name)
static
const QList< QgsExpression::Function * > & QgsExpression::Functions ( )
static

Definition at line 1436 of file qgsexpression.cpp.

References fcnAbs(), fcnAcos(), fcnAge(), fcnAsin(), fcnAtan(), fcnAtan2(), fcnBbox(), fcnBuffer(), fcnCeil(), fcnCentroid(), fcnClamp(), fcnCoalesce(), fcnColorCmyk(), fcnColorHsl(), fcnColorHsv(), fcnColorRgb(), fcnCombine(), fcnConcat(), fcnContains(), fcnConvexHull(), fcnCos(), fcnCrosses(), fcnDay(), fcnDifference(), fcnDisjoint(), fcnDistance(), fcnExp(), fcnExpScale(), fcnFeatureId(), fcnFloor(), fcnFormatDate(), fcnFormatNumber(), fcnFormatString(), fcnGeomArea(), fcnGeometry(), fcnGeomFromGML(), fcnGeomFromWKT(), fcnGeomLength(), fcnGeomPerimeter(), fcnGeomToWKT(), fcnHour(), fcnIntersection(), fcnIntersects(), fcnLeft(), fcnLength(), fcnLinearScale(), fcnLn(), fcnLog(), fcnLog10(), fcnLower(), fcnLPad(), fcnMax(), fcnMin(), fcnMinute(), fcnMonth(), fcnNow(), fcnOverlaps(), fcnPi(), fcnRampColor(), fcnRegexpMatch(), fcnRegexpReplace(), fcnRegexpSubstr(), fcnReplace(), fcnRight(), fcnRnd(), fcnRndF(), fcnRound(), fcnRowNumber(), fcnRPad(), fcnScale(), fcnSeconds(), fcnSin(), fcnSpecialColumn(), fcnSqrt(), fcnStrpos(), fcnSubstr(), fcnSymDifference(), fcnTan(), fcnTitle(), fcnToDate(), fcnToDateTime(), fcnToInt(), fcnToInterval(), fcnToReal(), fcnToString(), fcnToTime(), fcnTouches(), fcnTrim(), fcnUpper(), fcnUuid(), fcnWeek(), fcnWithin(), fcnX(), fcnXat(), fcnY(), fcnYat(), fcnYear(), fncColorCmyka(), fncColorHsla(), fncColorHsva(), fncColorRgba(), and gmFunctions.

Referenced by QgsExpression::NodeFunction::dump(), QgsExpression::NodeFunction::eval(), QgsOgcUtils::expressionFunctionToOgcFilter(), functionCount(), functionIndex(), geometryFromConstExpr(), isGeometryColumn(), QgsOgcUtils::nodeFunctionFromOgcFilter(), and QgsExpressionBuilderWidget::QgsExpressionBuilderWidget().

QgsDistanceArea* QgsExpression::geomCalculator ( )
inline

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

Definition at line 166 of file qgsexpression.h.

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

QString QgsExpression::group ( QString  group)
static

Definition at line 2388 of file qgsexpression.cpp.

References gGroups, and tr.

Referenced by QgsExpressionBuilderWidget::registerItem().

bool QgsExpression::hasEvalError ( ) const
inline
bool QgsExpression::hasParserError ( ) const
inline
bool QgsExpression::hasSpecialColumn ( const QString &  name)
static

Check whether a special column exists.

Note
added in 2.2

Definition at line 1586 of file qgsexpression.cpp.

References functionIndex(), gmSpecialColumns, and setSpecialColumn().

QString QgsExpression::helptext ( QString  name)
static
void QgsExpression::initFunctionHelp ( )
staticprotected

Definition at line 6 of file qgsexpression_texts.cpp.

References gFunctionHelpTexts.

Referenced by helptext().

void QgsExpression::initGeomCalculator ( )
protected

Definition at line 1688 of file qgsexpression.cpp.

References mCalc, and QgsDistanceArea::setEllipsoidalMode().

bool QgsExpression::isFunctionName ( QString  name)
static

Definition at line 1618 of file qgsexpression.cpp.

References functionIndex().

bool QgsExpression::needsGeometry ( )

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

Definition at line 1681 of file qgsexpression.cpp.

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

Referenced by QgsSearchQueryBuilder::countRecords(), QgsAttributeEditor::createAttributeEditor(), QgsAttributeDialog::init(), and QgsAttributeTableModel::loadAttributes().

QString QgsExpression::parserErrorString ( ) const
inline
bool QgsExpression::prepare ( const QgsFields fields)
static QString QgsExpression::quotedColumnRef ( QString  name)
inlinestatic
static QString QgsExpression::quotedString ( QString  text)
inlinestatic

return quoted string (in single quotes)

Definition at line 318 of file qgsexpression.h.

Referenced by QgsRuleBasedRendererV2::refineRuleCategories().

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

Definition at line 1373 of file qgsexpression.cpp.

References functionIndex(), and gmFunctions.

QString QgsExpression::replaceExpressionText ( const QString &  action,
const QgsFeature feat,
QgsVectorLayer layer,
const QMap< QString, QVariant > *  substitutionMap = 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

Definition at line 1753 of file qgsexpression.cpp.

References evalErrorString(), evaluate(), hasEvalError(), hasParserError(), index, parserErrorString(), QgsVectorLayer::pendingFields(), QgsDebugMsg, setSpecialColumn(), and specialColumn().

Referenced by QgsComposerLabel::displayText(), QgsAttributeAction::doAction(), QgsMapTip::fetchFeature(), and QgsHtmlAnnotationItem::setFeatureForMapPosition().

const Node* QgsExpression::rootNode ( ) const
inline

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

Definition at line 103 of file qgsexpression.h.

Referenced by QgsOgcUtils::expressionToOgcFilter(), and QgsSymbolLayerV2Utils::fieldOrExpressionFromExpression().

int QgsExpression::scale ( )
inline

Definition at line 156 of file qgsexpression.h.

Referenced by fcnScale().

void QgsExpression::setCurrentRowNumber ( int  rowNumber)
inline

Set the number for $rownum special column.

Definition at line 140 of file qgsexpression.h.

void QgsExpression::setEvalErrorString ( QString  str)
inline
void QgsExpression::setGeomCalculator ( const QgsDistanceArea calc)

Sets the geometry calculator used in evaluation of expressions,.

Definition at line 1698 of file qgsexpression.cpp.

References mCalc.

Referenced by QgsAttributeDialog::init(), and QgsExpressionBuilderWidget::on_txtExpressionString_textChanged().

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

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

Definition at line 1570 of file qgsexpression.cpp.

References functionIndex(), and gmSpecialColumns.

Referenced by fcnSpecialColumn(), and replaceExpressionText().

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

Returns a list of special Column definitions.

Definition at line 1608 of file qgsexpression.cpp.

References gmSpecialColumns.

Referenced by QgsExpressionBuilderWidget::QgsExpressionBuilderWidget().

bool QgsExpression::unregisterFunction ( QString  name)
static

Definition at line 1384 of file qgsexpression.cpp.

References BuiltinFunctions(), functionIndex(), and gmFunctions.

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

Unset a special column.

Definition at line 1561 of file qgsexpression.cpp.

References gmSpecialColumns.

Friends And Related Function Documentation

friend class QgsOgcUtils
friend

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

Referenced by QgsExpression::NodeBinaryOperator::dump(), and QgsOgcUtils::expressionBinaryOperatorToOgcFilter().

QHash< QString, QString > QgsExpression::gFunctionHelpTexts
staticprotected

Definition at line 623 of file qgsexpression.h.

Referenced by helptext(), and initFunctionHelp().

QHash< QString, QString > QgsExpression::gGroups
staticprotected

Definition at line 624 of file qgsexpression.h.

Referenced by group().

QStringList QgsExpression::gmBuiltinFunctions
static

Definition at line 293 of file qgsexpression.h.

Referenced by BuiltinFunctions().

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

Definition at line 291 of file qgsexpression.h.

Referenced by Functions(), registerFunction(), and unregisterFunction().

QMap< QString, QVariant > QgsExpression::gmSpecialColumns
staticprotected
QgsDistanceArea* QgsExpression::mCalc
protected

Definition at line 618 of file qgsexpression.h.

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

QString QgsExpression::mEvalErrorString
protected

Definition at line 611 of file qgsexpression.h.

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

QString QgsExpression::mExp
protected

Definition at line 615 of file qgsexpression.h.

Referenced by QgsOgcUtils::expressionFromOgcFilter().

QString QgsExpression::mParserErrorString
protected

Definition at line 610 of file qgsexpression.h.

Referenced by QgsOgcUtils::expressionFromOgcFilter(), and QgsExpression().

Node* QgsExpression::mRootNode
protected
int QgsExpression::mRowNumber
protected

Definition at line 613 of file qgsexpression.h.

double QgsExpression::mScale
protected

Definition at line 614 of file qgsexpression.h.

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

Definition at line 233 of file qgsexpression.h.

Referenced by QgsExpression::NodeUnaryOperator::dump(), and QgsOgcUtils::expressionUnaryOperatorToOgcFilter().


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