QGIS API Documentation
2.12.0-Lyon
|
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... | |
struct | Help |
struct | HelpArg |
struct | HelpExample |
struct | HelpVariant |
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, boIntDiv, boMod, boPow, boConcat } |
list of binary operators More... | |
typedef QVariant(* | FcnEval) (const QVariantList &values, const QgsFeature *f, QgsExpression *parent) |
typedef QVariant(* | FcnEvalContext) (const QVariantList &values, const QgsExpressionContext *context, QgsExpression *parent) |
Function definition for evaluation against an expression context. More... | |
enum | NodeType { ntUnaryOperator, ntBinaryOperator, ntInOperator, ntFunction, ntLiteral, ntColumnRef, ntCondition } |
enum | SpatialOperator { soBbox, soIntersects, soContains, soCrosses, soEquals, soDisjoint, soOverlaps, soTouches, soWithin } |
enum | UnaryOperator { uoNot, uoMinus } |
list of unary operators More... | |
typedef QList< WhenThen * > | WhenThenList |
Public Member Functions | |
QgsExpression (const QString &expr) | |
~QgsExpression () | |
void | acceptVisitor (Visitor &v) const |
Entry function for the visitor pattern. More... | |
Q_DECL_DEPRECATED 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... | |
Q_DECL_DEPRECATED QVariant | evaluate (const QgsFeature *f) |
Evaluate the feature and return the result. More... | |
Q_DECL_DEPRECATED QVariant | evaluate (const QgsFeature &f) |
Evaluate the feature and return the result. More... | |
Q_DECL_DEPRECATED QVariant | evaluate (const QgsFeature *f, const QgsFields &fields) |
Evaluate the feature and return the result. More... | |
Q_DECL_DEPRECATED QVariant | evaluate (const QgsFeature &f, const QgsFields &fields) |
Evaluate the feature and return the result. More... | |
QVariant | evaluate () |
Evaluate the feature and return the result. More... | |
QVariant | evaluate (const QgsExpressionContext *context) |
Evaluate the expression against the specified context and return the result. More... | |
const QString | expression () const |
Alias for dump() More... | |
QgsDistanceArea * | geomCalculator () |
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 | isField () const |
Checks whether an expression consists only of a single field reference. More... | |
bool | needsGeometry () const |
Returns true if the expression uses feature geometry for some computation. More... | |
QString | parserErrorString () const |
Returns parser error. More... | |
Q_DECL_DEPRECATED bool | prepare (const QgsFields &fields) |
Get the expression ready for evaluation - find out column indexes. More... | |
bool | prepare (const QgsExpressionContext *context) |
Get the expression ready for evaluation - find out column indexes. More... | |
QStringList | referencedColumns () const |
Get list of columns referenced by the expression. More... | |
const Node * | rootNode () const |
Returns root node of the expression. Root node is null is parsing has failed. More... | |
double | scale () |
Q_DECL_DEPRECATED void | setCurrentRowNumber (int rowNumber) |
Set the number for $rownum special column. More... | |
void | setEvalErrorString (const 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 void | cleanRegisteredFunctions () |
Deletes all registered functions whose ownership have been transferred to the expression engine. More... | |
static double | evaluateToDouble (const QString &text, const double fallbackValue) |
Attempts to evaluate a text string as an expression to a resultant double value. More... | |
static int | functionCount () |
Returns the number of functions defined in the parser. More... | |
static int | functionIndex (const QString &name) |
static const QList< Function * > & | Functions () |
static QString | group (const QString &group) |
Returns the translated name for a function group. More... | |
static bool | hasSpecialColumn (const QString &name) |
Check whether a special column exists. More... | |
static QString | helptext (QString name) |
Returns the help text for a specified function. More... | |
static bool | isFunctionName (const QString &name) |
static Q_DECL_DEPRECATED bool | isValid (const QString &text, const QgsFields &fields, QString &errorMessage) |
static bool | isValid (const QString &text, const QgsExpressionContext *context, QString &errorMessage) |
Tests whether a string is a valid expression. 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 bool | registerFunction (Function *function, bool transferOwnership=false) |
Registers a function to the expression engine. More... | |
static Q_DECL_DEPRECATED 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 QString | replaceExpressionText (const QString &action, const QgsExpressionContext *context, const QMap< QString, QVariant > *substitutionMap=0, const QgsDistanceArea *distanceArea=0) |
This function replaces each expression between [% and %] in the string with the result of its evaluation with the specified context. More... | |
static Q_DECL_DEPRECATED void | setSpecialColumn (const QString &name, const QVariant &value) |
Assign a special column. More... | |
static Q_DECL_DEPRECATED 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 (const QString &name) |
Unregisters a function from the expression engine. More... | |
static Q_DECL_DEPRECATED void | unsetSpecialColumn (const QString &name) |
Unset a special column. More... | |
static QString | variableHelpText (const QString &variableName, bool showValue=true, const QVariant &value=QVariant()) |
Returns the help text for a specified variable. More... | |
Static Public Attributes | |
static const char * | BinaryOperatorText [] |
static QStringList | gmBuiltinFunctions |
static QList< Function * > | gmFunctions |
static QList< Function * > | gmOwnedFunctions |
List of functions owned by the expression engine. More... | |
static const char * | UnaryOperatorText [] |
Protected Member Functions | |
QgsExpression () | |
Used by QgsOgcUtils to create an empty. More... | |
void | initGeomCalculator () |
Static Protected Member Functions | |
static void | initFunctionHelp () |
static void | initVariableHelp () |
Protected Attributes | |
QgsDistanceArea * | mCalc |
QString | mEvalErrorString |
QString | mExp |
QString | mParserErrorString |
Node * | mRootNode |
int | mRowNumber |
double | mScale |
Static Protected Attributes | |
static QHash< QString, Help > | gFunctionHelpTexts |
static QHash< QString, QString > | gGroups |
static QMap< QString, QString > | gmSpecialColumnGroups |
static QMap< QString, QVariant > | gmSpecialColumns |
static QHash< QString, QString > | gVariableHelpTexts |
Friends | |
class | QgsOgcUtils |
Class for parsing and evaluation of expressions (formerly called "search strings").
The expressions try to follow both syntax and semantics of SQL expressions.
Usage:
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 92 of file qgsexpression.h.
typedef QVariant( * QgsExpression::FcnEval) (const QVariantList &values, const QgsFeature *f, QgsExpression *parent) |
Definition at line 343 of file qgsexpression.h.
typedef QVariant( * QgsExpression::FcnEvalContext) (const QVariantList &values, const QgsExpressionContext *context, QgsExpression *parent) |
Function definition for evaluation against an expression context.
Definition at line 347 of file qgsexpression.h.
typedef QList<WhenThen*> QgsExpression::WhenThenList |
Definition at line 859 of file qgsexpression.h.
list of binary operators
Enumerator | |
---|---|
boOr | |
boAnd | |
boEQ | |
boNE | |
boLE | |
boGE | |
boLT | |
boGT | |
boRegexp | |
boLike | |
boNotLike | |
boILike | |
boNotILike | |
boIs | |
boIsNot | |
boPlus | |
boMinus | |
boMul | |
boDiv | |
boIntDiv | |
boMod | |
boPow | |
boConcat |
Definition at line 294 of file qgsexpression.h.
Enumerator | |
---|---|
ntUnaryOperator | |
ntBinaryOperator | |
ntInOperator | |
ntFunction | |
ntLiteral | |
ntColumnRef | |
ntCondition |
Definition at line 555 of file qgsexpression.h.
Enumerator | |
---|---|
soBbox | |
soIntersects | |
soContains | |
soCrosses | |
soEquals | |
soDisjoint | |
soOverlaps | |
soTouches | |
soWithin |
Definition at line 327 of file qgsexpression.h.
list of unary operators
Enumerator | |
---|---|
uoNot | |
uoMinus |
Definition at line 284 of file qgsexpression.h.
QgsExpression::QgsExpression | ( | const QString & | expr | ) |
Definition at line 2468 of file qgsexpression.cpp.
QgsExpression::~QgsExpression | ( | ) |
Definition at line 2480 of file qgsexpression.cpp.
|
inlineprotected |
Used by QgsOgcUtils to create an empty.
Definition at line 925 of file qgsexpression.h.
void QgsExpression::acceptVisitor | ( | QgsExpression::Visitor & | v | ) | const |
Entry function for the visitor pattern.
Definition at line 2630 of file qgsexpression.cpp.
|
static |
Definition at line 2143 of file qgsexpression.cpp.
|
static |
Deletes all registered functions whose ownership have been transferred to the expression engine.
Definition at line 2135 of file qgsexpression.cpp.
|
inline |
Return the number used for $rownum special column.
Definition at line 172 of file qgsexpression.h.
QString QgsExpression::dump | ( | ) | const |
Return the expression string that represents this QgsExpression.
Definition at line 2622 of file qgsexpression.cpp.
|
inline |
Returns evaluation error.
Definition at line 165 of file qgsexpression.h.
QVariant QgsExpression::evaluate | ( | const QgsFeature * | f | ) |
Evaluate the feature and return the result.
Definition at line 2559 of file qgsexpression.cpp.
QVariant QgsExpression::evaluate | ( | const QgsFeature & | f | ) |
Evaluate the feature and return the result.
Definition at line 2572 of file qgsexpression.cpp.
QVariant QgsExpression::evaluate | ( | const QgsFeature * | f, |
const QgsFields & | fields | ||
) |
Evaluate the feature and return the result.
Definition at line 2579 of file qgsexpression.cpp.
|
inline |
Evaluate the feature and return the result.
Definition at line 2591 of file qgsexpression.cpp.
QVariant QgsExpression::evaluate | ( | ) |
Evaluate the feature and return the result.
Definition at line 2598 of file qgsexpression.cpp.
QVariant QgsExpression::evaluate | ( | const QgsExpressionContext * | context | ) |
Evaluate the expression against the specified context and return the result.
context | context for evaluating expression |
Definition at line 2610 of file qgsexpression.cpp.
|
static |
Attempts to evaluate a text string as an expression to a resultant double value.
text | text to evaluate as expression |
fallbackValue | value to return if text can not be evaluated as a double |
Definition at line 2719 of file qgsexpression.cpp.
|
inline |
Alias for dump()
Definition at line 215 of file qgsexpression.h.
|
static |
Returns the number of functions defined in the parser.
Definition at line 2462 of file qgsexpression.cpp.
|
static |
Definition at line 2446 of file qgsexpression.cpp.
|
static |
Definition at line 2190 of file qgsexpression.cpp.
|
inline |
Return calculator used for distance and area calculations (used by internal functions)
Definition at line 228 of file qgsexpression.h.
Returns the translated name for a function group.
group | untranslated group name |
Definition at line 3655 of file qgsexpression.cpp.
|
inline |
Returns true if an error occurred when evaluating last input.
Definition at line 163 of file qgsexpression.h.
|
inline |
Returns true if an error occurred when parsing the input expression.
Definition at line 100 of file qgsexpression.h.
|
static |
Check whether a special column exists.
Definition at line 2394 of file qgsexpression.cpp.
Returns the help text for a specified function.
name | function name |
Definition at line 3459 of file qgsexpression.cpp.
|
staticprotected |
Definition at line 5 of file qgsexpression_texts.cpp.
|
protected |
Definition at line 2517 of file qgsexpression.cpp.
|
staticprotected |
Definition at line 3576 of file qgsexpression.cpp.
|
inline |
Checks whether an expression consists only of a single field reference.
Definition at line 197 of file qgsexpression.h.
|
static |
Definition at line 2441 of file qgsexpression.cpp.
|
static |
Definition at line 2401 of file qgsexpression.cpp.
|
static |
Tests whether a string is a valid expression.
text | string to test |
context | optional expression context |
errorMessage | will be filled with any error message from the validation |
Definition at line 2407 of file qgsexpression.cpp.
bool QgsExpression::needsGeometry | ( | ) | const |
Returns true if the expression uses feature geometry for some computation.
Definition at line 2510 of file qgsexpression.cpp.
|
inline |
Returns parser error.
Definition at line 102 of file qgsexpression.h.
bool QgsExpression::prepare | ( | const QgsFields & | fields | ) |
Get the expression ready for evaluation - find out column indexes.
Definition at line 2533 of file qgsexpression.cpp.
bool QgsExpression::prepare | ( | const QgsExpressionContext * | context | ) |
Get the expression ready for evaluation - find out column indexes.
context | context for preparing expression |
Definition at line 2539 of file qgsexpression.cpp.
return quoted column reference (in double quotes)
Definition at line 2427 of file qgsexpression.cpp.
return quoted string (in single quotes)
Definition at line 2432 of file qgsexpression.cpp.
QStringList QgsExpression::referencedColumns | ( | ) | const |
Get list of columns referenced by the expression.
Definition at line 2486 of file qgsexpression.cpp.
|
static |
Registers a function to the expression engine.
This is required to allow expressions to utilise the function.
function | function to register |
transferOwnership | set to true to transfer ownership of function to expression engine |
Definition at line 2106 of file qgsexpression.cpp.
|
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
action | |
feat | |
layer | |
substitutionMap | |
distanceArea | optional QgsDistanceArea. If specified, the QgsDistanceArea is used for distance and area conversion |
Definition at line 2636 of file qgsexpression.cpp.
|
static |
This function replaces each expression between [% and %] in the string with the result of its evaluation with the specified context.
Additional substitutions can be passed through the substitutionMap parameter
action | |
context | expression context |
substitutionMap | |
distanceArea | optional QgsDistanceArea. If specified, the QgsDistanceArea is used for distance and area conversion |
Definition at line 2644 of file qgsexpression.cpp.
|
inline |
Returns root node of the expression. Root node is null is parsing has failed.
Definition at line 107 of file qgsexpression.h.
|
inline |
Definition at line 212 of file qgsexpression.h.
|
inline |
Set the number for $rownum special column.
Definition at line 170 of file qgsexpression.h.
|
inline |
Set evaluation error (used internally by evaluation functions)
Definition at line 167 of file qgsexpression.h.
void QgsExpression::setGeomCalculator | ( | const QgsDistanceArea & | calc | ) |
Sets the geometry calculator used in evaluation of expressions,.
Definition at line 2527 of file qgsexpression.cpp.
|
inline |
Definition at line 210 of file qgsexpression.h.
Assign a special column.
Definition at line 2358 of file qgsexpression.cpp.
Return the value of the given special column or a null QVariant if undefined.
Definition at line 2378 of file qgsexpression.cpp.
|
static |
Returns a list of special Column definitions.
Definition at line 2415 of file qgsexpression.cpp.
|
static |
Unregisters a function from the expression engine.
The function will no longer be usable in expressions.
name | function name |
Definition at line 2119 of file qgsexpression.cpp.
|
static |
Unset a special column.
Definition at line 2369 of file qgsexpression.cpp.
|
static |
Returns the help text for a specified variable.
variableName | name of variable |
showValue | set to true to include current value of variable in help text |
value | current value of variable to show in help text |
Definition at line 3629 of file qgsexpression.cpp.
|
friend |
Definition at line 1018 of file qgsexpression.h.
|
static |
Definition at line 340 of file qgsexpression.h.
|
staticprotected |
Definition at line 1011 of file qgsexpression.h.
Definition at line 1013 of file qgsexpression.h.
|
static |
Definition at line 505 of file qgsexpression.h.
|
static |
Definition at line 502 of file qgsexpression.h.
|
static |
List of functions owned by the expression engine.
Definition at line 523 of file qgsexpression.h.
Definition at line 941 of file qgsexpression.h.
Definition at line 940 of file qgsexpression.h.
Definition at line 1012 of file qgsexpression.h.
|
protected |
Definition at line 938 of file qgsexpression.h.
|
protected |
Definition at line 932 of file qgsexpression.h.
|
protected |
Definition at line 936 of file qgsexpression.h.
|
protected |
Definition at line 931 of file qgsexpression.h.
|
protected |
Definition at line 929 of file qgsexpression.h.
|
protected |
Definition at line 934 of file qgsexpression.h.
|
protected |
Definition at line 935 of file qgsexpression.h.
|
static |
Definition at line 341 of file qgsexpression.h.