Quantum GIS API Documentation
1.8
|
Class for parsing and evaluation of expressions (formerly called "search strings"). More...
#include <qgsexpression.h>
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. | |
QgsDistanceArea * | geomCalculator () |
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 QgsExpression * | createFromOgcFilter (QDomElement &element) |
Static Public Attributes | |
static const char * | BinaryOperatorText [] |
static const char * | UnaryOperatorText [] |
static const char * | BinaryOgcOperatorText [] |
static const char * | UnaryOgcOperatorText [] |
static QList< FunctionDef > | gmBuiltinFunctions |
Protected Member Functions | |
QgsExpression () | |
void | initGeomCalculator () |
Protected Attributes | |
QString | mExpression |
Node * | mRootNode |
QString | mParserErrorString |
QString | mEvalErrorString |
int | mRowNumber |
QgsDistanceArea * | mCalc |
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 82 of file qgsexpression.h.
typedef QVariant( * QgsExpression::FcnEval)(const QVariantList &values, QgsFeature *f, QgsExpression *parent) |
Definition at line 176 of file qgsexpression.h.
typedef QList<WhenThen*> QgsExpression::WhenThenList |
Definition at line 423 of file qgsexpression.h.
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.
Definition at line 132 of file qgsexpression.h.
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.
QgsExpression::QgsExpression | ( | ) | [inline, protected] |
Definition at line 472 of file qgsexpression.h.
Referenced by createFromOgcFilter().
void QgsExpression::acceptVisitor | ( | QgsExpression::Visitor & | v | ) |
entry function for the visitor pattern
Definition at line 623 of file qgsexpression.cpp.
References QgsExpression::Node::accept(), and mRootNode.
const QList< QgsExpression::FunctionDef > & QgsExpression::BuiltinFunctions | ( | ) | [static] |
Definition at line 412 of file qgsexpression.cpp.
References fcnAcos(), fcnAsin(), fcnAtan(), fcnAtan2(), fcnCos(), fcnExp(), fcnFeatureId(), fcnGeomArea(), fcnGeomLength(), fcnGeomPerimeter(), fcnLength(), fcnLn(), fcnLog(), fcnLog10(), fcnLower(), fcnRegexpReplace(), fcnReplace(), fcnRowNumber(), fcnSin(), fcnSqrt(), fcnSubstr(), fcnTan(), fcnToInt(), fcnToReal(), fcnToString(), fcnUpper(), fcnX(), fcnXat(), fcnY(), fcnYat(), and gmBuiltinFunctions.
Referenced by QgsExpression::NodeFunction::createFromOgcFilter(), QgsExpression::NodeFunction::dump(), QgsExpression::NodeFunction::eval(), functionCount(), functionIndex(), QgsExpressionBuilderWidget::QgsExpressionBuilderWidget(), and QgsExpression::NodeFunction::toOgcFilter().
QgsExpression * QgsExpression::createFromOgcFilter | ( | QDomElement & | element | ) | [static] |
Definition at line 588 of file qgsexpression.cpp.
References boConcat, mParserErrorString, mRootNode, and QgsExpression().
Referenced by QgsExpression::NodeUnaryOperator::createFromOgcFilter(), QgsExpression::NodeBinaryOperator::createFromOgcFilter(), QgsExpression::NodeFunction::createFromOgcFilter(), QgsExpression::NodeLiteral::createFromOgcFilter(), QgsRuleBasedRendererV2::Rule::createFromSld(), and QgsSymbolLayerV2Utils::functionFromSldElement().
int QgsExpression::currentRowNumber | ( | ) | [inline] |
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] |
Returns evaluation error.
Definition at line 114 of file qgsexpression.h.
Referenced by QgsSearchQueryBuilder::countRecords(), QgsAttributeAction::expandAction(), QgsExpressionBuilderWidget::on_txtExpressionString_textChanged(), and QgsPalLayerSettings::registerFeature().
QVariant QgsExpression::evaluate | ( | QgsFeature * | f = NULL | ) |
Evaluate the feature and return the result.
Definition at line 549 of file qgsexpression.cpp.
References QgsExpression::Node::eval(), mEvalErrorString, and mRootNode.
Referenced by QgsSearchQueryBuilder::countRecords(), evaluate(), QgsAttributeAction::expandAction(), QgsExpressionBuilderWidget::on_txtExpressionString_textChanged(), and QgsPalLayerSettings::registerFeature().
QVariant QgsExpression::evaluate | ( | QgsFeature * | f, |
const QgsFieldMap & | fields | ||
) |
Evaluate the feature and return the result.
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.
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().
QgsDistanceArea* QgsExpression::geomCalculator | ( | ) | [inline] |
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] |
Returns true if an error occurred when evaluating last input.
Definition at line 112 of file qgsexpression.h.
Referenced by QgsSearchQueryBuilder::countRecords(), QgsAttributeAction::expandAction(), QgsExpressionBuilderWidget::on_txtExpressionString_textChanged(), and QgsPalLayerSettings::registerFeature().
bool QgsExpression::hasParserError | ( | ) | const [inline] |
Returns true if an error occurred when parsing the input expression.
Definition at line 89 of file qgsexpression.h.
Referenced by QgsSearchQueryBuilder::countRecords(), QgsRuleBasedRendererV2::Rule::createFromSld(), QgsSymbolLayerV2Utils::createFunctionElement(), QgsAttributeAction::expandAction(), QgsSymbolLayerV2Utils::functionFromSldElement(), QgsSearchQueryBuilder::loadQuery(), QgsExpressionBuilderWidget::on_txtExpressionString_textChanged(), and QgsPalLayerSettings::registerFeature().
void QgsExpression::initGeomCalculator | ( | ) | [protected] |
Definition at line 528 of file qgsexpression.cpp.
References mCalc, QgsDistanceArea::setEllipsoid(), and QgsDistanceArea::setProjectionsEnabled().
bool QgsExpression::isFunctionName | ( | QString | name | ) | [static] |
Definition at line 459 of file qgsexpression.cpp.
References functionIndex().
bool QgsExpression::needsGeometry | ( | ) |
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] |
Returns parser error.
Definition at line 91 of file qgsexpression.h.
Referenced by QgsSearchQueryBuilder::countRecords(), QgsRuleBasedRendererV2::Rule::createFromSld(), QgsSymbolLayerV2Utils::createFunctionElement(), QgsAttributeAction::expandAction(), QgsSymbolLayerV2Utils::functionFromSldElement(), QgsSearchQueryBuilder::loadQuery(), QgsExpressionBuilderWidget::on_txtExpressionString_textChanged(), and QgsPalLayerSettings::registerFeature().
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().
QStringList QgsExpression::referencedColumns | ( | ) |
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 |
Definition at line 580 of file qgsexpression.cpp.
References mRootNode, and QgsExpression::Node::toOgcFilter().
Referenced by QgsSymbolLayerV2Utils::createFunctionElement(), and QgsExpression::NodeBinaryOperator::toOgcFilter().
const char * QgsExpression::BinaryOgcOperatorText [static] |
{ "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] |
{ "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().
QList< QgsExpression::FunctionDef > QgsExpression::gmBuiltinFunctions [static] |
Definition at line 197 of file qgsexpression.h.
Referenced by BuiltinFunctions().
QgsDistanceArea* QgsExpression::mCalc [protected] |
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().
Node* QgsExpression::mRootNode [protected] |
Definition at line 475 of file qgsexpression.h.
Referenced by acceptVisitor(), createFromOgcFilter(), dump(), evaluate(), needsGeometry(), prepare(), QgsExpression(), referencedColumns(), toOgcFilter(), and ~QgsExpression().
int QgsExpression::mRowNumber [protected] |
Definition at line 480 of file qgsexpression.h.
const char * QgsExpression::UnaryOgcOperatorText [static] |
{ "Not", "" }
Definition at line 174 of file qgsexpression.h.
Referenced by QgsExpression::Node::createFromOgcFilter(), and QgsExpression::NodeUnaryOperator::createFromOgcFilter().
const char * QgsExpression::UnaryOperatorText [static] |
{ "NOT", "-" }
Definition at line 171 of file qgsexpression.h.
Referenced by QgsExpression::NodeUnaryOperator::dump(), and QgsExpression::NodeUnaryOperator::toOgcFilter().