QGIS API Documentation
2.14.0-Essen
|
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 |
c++ helper class for defining QgsExpression functions. More... | |
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) | |
Creates a new expression based on the provided string. More... | |
QgsExpression (const QgsExpression &other) | |
Create a copy of this expression. More... | |
~QgsExpression () | |
void | acceptVisitor (Visitor &v) const |
Entry function for the visitor pattern. More... | |
QgsUnitTypes::AreaUnit | areaUnits () const |
Returns the desired areal units for calculations involving geomCalculator(), eg "$area". More... | |
Q_DECL_DEPRECATED int | currentRowNumber () |
Return the number used for $rownum special column. More... | |
QGis::UnitType | distanceUnits () const |
Returns the desired distance units for calculations involving geomCalculator(), eg "$length" and "$perimeter". More... | |
QString | dump () const |
Return an expression string, constructed from the internal abstract syntax tree. 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... | |
QString | expression () const |
Return the original, unmodified expression string. More... | |
QgsDistanceArea * | geomCalculator () |
Return calculator used for distance and area calculations (used by $length, $area and $perimeter functions only) 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... | |
QgsExpression & | operator= (const QgsExpression &other) |
Create a copy of this expression. 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 () |
void | setAreaUnits (QgsUnitTypes::AreaUnit unit) |
Sets the desired areal units for calculations involving geomCalculator(), eg "$area". More... | |
Q_DECL_DEPRECATED void | setCurrentRowNumber (int rowNumber) |
Set the number for $rownum special column. More... | |
void | setDistanceUnits (QGis::UnitType unit) |
Sets the desired distance units for calculations involving geomCalculator(), eg "$length" and "$perimeter". 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 for distance and area calculations in 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 QString | formatPreviewString (const QVariant &value) |
Formats an expression result for friendly display to the user. More... | |
static int | functionCount () |
Returns the number of functions defined in the parser. More... | |
static int | functionIndex (const QString &name) |
return index of the function in Functions array More... | |
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) |
tells whether the identifier is a name of existing function More... | |
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) |
Returns a quoted column reference (in double quotes) More... | |
static QString | quotedString (QString text) |
Returns a quoted version of a string (in single quotes) More... | |
static QString | quotedValue (const QVariant &value) |
Returns a string representation of a literal value, including appropriate quotations where required. More... | |
static QString | quotedValue (const QVariant &value, QVariant::Type type) |
Returns a string representation of a literal value, including appropriate quotations where required. 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=nullptr, const QgsDistanceArea *distanceArea=nullptr) |
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=nullptr, const QgsDistanceArea *distanceArea=nullptr) |
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 | detach () |
Helper for implicit sharing. More... | |
void | initGeomCalculator () |
Static Protected Member Functions | |
static void | initFunctionHelp () |
static void | initVariableHelp () |
Protected Attributes | |
QgsExpressionPrivate * | d |
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:
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).
Operators and functions that expect arguments to be of a 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 to_int, to_real, to_string 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.
This class is implicitly shared, copying has a very low overhead. It is normally preferable to call QgsExpression( otherExpression )
instead of QgsExpression( otherExpression.expression() )
. A deep copy will only be made when prepare() is called. For usage this means mainly, that you should normally keep an unprepared master copy of a QgsExpression and whenever using it with a particular QgsFeatureIterator copy it just before and prepare it using the same context as the iterator.
Implicit sharing was added in 2.14
Definition at line 107 of file qgsexpression.h.
typedef QVariant( * QgsExpression::FcnEval) (const QVariantList &values, const QgsFeature *f, QgsExpression *parent) |
Definition at line 427 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 431 of file qgsexpression.h.
typedef QList<WhenThen*> QgsExpression::WhenThenList |
Definition at line 1017 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 374 of file qgsexpression.h.
Enumerator | |
---|---|
ntUnaryOperator | |
ntBinaryOperator | |
ntInOperator | |
ntFunction | |
ntLiteral | |
ntColumnRef | |
ntCondition |
Definition at line 675 of file qgsexpression.h.
Enumerator | |
---|---|
soBbox | |
soIntersects | |
soContains | |
soCrosses | |
soEquals | |
soDisjoint | |
soOverlaps | |
soTouches | |
soWithin |
Definition at line 408 of file qgsexpression.h.
list of unary operators
Enumerator | |
---|---|
uoNot | |
uoMinus |
Definition at line 364 of file qgsexpression.h.
QgsExpression::QgsExpression | ( | const QString & | expr | ) |
Creates a new expression based on the provided string.
The string will immediately be parsed. For optimization prepare() should alwys be called before every loop in which this expression is used.
Definition at line 3198 of file qgsexpression.cpp.
QgsExpression::QgsExpression | ( | const QgsExpression & | other | ) |
Create a copy of this expression.
This is preferred over recreating an expression from a string since it does not need to be re-parsed.
Definition at line 3206 of file qgsexpression.cpp.
QgsExpression::~QgsExpression | ( | ) |
Definition at line 3224 of file qgsexpression.cpp.
|
protected |
Used by QgsOgcUtils to create an empty.
Definition at line 3219 of file qgsexpression.cpp.
void QgsExpression::acceptVisitor | ( | QgsExpression::Visitor & | v | ) | const |
Entry function for the visitor pattern.
Definition at line 3439 of file qgsexpression.cpp.
QgsUnitTypes::AreaUnit QgsExpression::areaUnits | ( | ) | const |
Returns the desired areal units for calculations involving geomCalculator(), eg "$area".
Definition at line 3429 of file qgsexpression.cpp.
|
static |
Definition at line 2800 of file qgsexpression.cpp.
|
static |
Deletes all registered functions whose ownership have been transferred to the expression engine.
Definition at line 2792 of file qgsexpression.cpp.
int QgsExpression::currentRowNumber | ( | ) |
Return the number used for $rownum special column.
Definition at line 3404 of file qgsexpression.cpp.
|
protected |
Helper for implicit sharing.
When called will create a new deep copy of this expression.
Definition at line 3276 of file qgsexpression.cpp.
QGis::UnitType QgsExpression::distanceUnits | ( | ) | const |
Returns the desired distance units for calculations involving geomCalculator(), eg "$length" and "$perimeter".
Definition at line 3419 of file qgsexpression.cpp.
QString QgsExpression::dump | ( | ) | const |
Return an expression string, constructed from the internal abstract syntax tree.
This does not contain any nice whitespace formatting or comments. In general it is preferrable to use expression() instead.
Definition at line 3406 of file qgsexpression.cpp.
QString QgsExpression::evalErrorString | ( | ) | const |
Returns evaluation error.
Definition at line 3389 of file qgsexpression.cpp.
QVariant QgsExpression::evaluate | ( | const QgsFeature * | f | ) |
Evaluate the feature and return the result.
Definition at line 3321 of file qgsexpression.cpp.
QVariant QgsExpression::evaluate | ( | const QgsFeature & | f | ) |
Evaluate the feature and return the result.
Definition at line 3334 of file qgsexpression.cpp.
QVariant QgsExpression::evaluate | ( | const QgsFeature * | f, |
const QgsFields & | fields | ||
) |
Evaluate the feature and return the result.
Definition at line 3341 of file qgsexpression.cpp.
|
inline |
Evaluate the feature and return the result.
Definition at line 3353 of file qgsexpression.cpp.
QVariant QgsExpression::evaluate | ( | ) |
Evaluate the feature and return the result.
Definition at line 3360 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 3372 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 3528 of file qgsexpression.cpp.
QString QgsExpression::expression | ( | ) | const |
Return the original, unmodified expression string.
If there was none supplied because it was constructed by sole API calls, dump() will be used to create one instead.
Definition at line 3110 of file qgsexpression.cpp.
Formats an expression result for friendly display to the user.
Truncates the result to a sensible length, and presents text representations of non numeric/text types (eg geometries and features).
value | expression result to format |
Definition at line 4620 of file qgsexpression.cpp.
|
static |
Returns the number of functions defined in the parser.
Definition at line 3192 of file qgsexpression.cpp.
|
static |
return index of the function in Functions array
Definition at line 3176 of file qgsexpression.cpp.
|
static |
Definition at line 2853 of file qgsexpression.cpp.
QgsDistanceArea * QgsExpression::geomCalculator | ( | ) |
Return calculator used for distance and area calculations (used by $length, $area and $perimeter functions only)
Definition at line 3414 of file qgsexpression.cpp.
Returns the translated name for a function group.
group | untranslated group name |
Definition at line 4594 of file qgsexpression.cpp.
bool QgsExpression::hasEvalError | ( | ) | const |
Returns true if an error occurred when evaluating last input.
Definition at line 3384 of file qgsexpression.cpp.
bool QgsExpression::hasParserError | ( | ) | const |
Returns true if an error occurred when parsing the input expression.
Definition at line 3231 of file qgsexpression.cpp.
|
static |
Check whether a special column exists.
Definition at line 3085 of file qgsexpression.cpp.
Returns the help text for a specified function.
name | function name |
Definition at line 4388 of file qgsexpression.cpp.
|
staticprotected |
Definition at line 5 of file qgsexpression_texts.cpp.
|
protected |
Definition at line 3266 of file qgsexpression.cpp.
|
staticprotected |
Definition at line 4505 of file qgsexpression.cpp.
|
inline |
Checks whether an expression consists only of a single field reference.
Definition at line 238 of file qgsexpression.h.
|
static |
tells whether the identifier is a name of existing function
Definition at line 3171 of file qgsexpression.cpp.
|
static |
Definition at line 3092 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 3098 of file qgsexpression.cpp.
bool QgsExpression::needsGeometry | ( | ) | const |
Returns true if the expression uses feature geometry for some computation.
Definition at line 3259 of file qgsexpression.cpp.
QgsExpression & QgsExpression::operator= | ( | const QgsExpression & | other | ) |
Create a copy of this expression.
This is preferred over recreating an expression from a string since it does not need to be re-parsed.
Definition at line 3212 of file qgsexpression.cpp.
QString QgsExpression::parserErrorString | ( | ) | const |
Returns parser error.
Definition at line 3233 of file qgsexpression.cpp.
bool QgsExpression::prepare | ( | const QgsFields & | fields | ) |
Get the expression ready for evaluation - find out column indexes.
Definition at line 3293 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 3300 of file qgsexpression.cpp.
Returns a quoted column reference (in double quotes)
Definition at line 3130 of file qgsexpression.cpp.
Returns a quoted version of a string (in single quotes)
Definition at line 3135 of file qgsexpression.cpp.
Returns a string representation of a literal value, including appropriate quotations where required.
value | value to convert to a string representation |
Definition at line 3144 of file qgsexpression.cpp.
Returns a string representation of a literal value, including appropriate quotations where required.
value | value to convert to a string representation |
type | value type |
Definition at line 3149 of file qgsexpression.cpp.
QStringList QgsExpression::referencedColumns | ( | ) | const |
Get list of columns referenced by the expression.
TODO QGIS3: Return QSet<QString>
Definition at line 3235 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 2763 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 3445 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 3453 of file qgsexpression.cpp.
const QgsExpression::Node * QgsExpression::rootNode | ( | ) | const |
Returns root node of the expression. Root node is null is parsing has failed.
Definition at line 4739 of file qgsexpression.cpp.
double QgsExpression::scale | ( | ) |
Definition at line 3108 of file qgsexpression.cpp.
void QgsExpression::setAreaUnits | ( | QgsUnitTypes::AreaUnit | unit | ) |
Sets the desired areal units for calculations involving geomCalculator(), eg "$area".
Definition at line 3434 of file qgsexpression.cpp.
void QgsExpression::setCurrentRowNumber | ( | int | rowNumber | ) |
Set the number for $rownum special column.
Definition at line 3399 of file qgsexpression.cpp.
void QgsExpression::setDistanceUnits | ( | QGis::UnitType | unit | ) |
Sets the desired distance units for calculations involving geomCalculator(), eg "$length" and "$perimeter".
Definition at line 3424 of file qgsexpression.cpp.
void QgsExpression::setEvalErrorString | ( | const QString & | str | ) |
Set evaluation error (used internally by evaluation functions)
Definition at line 3394 of file qgsexpression.cpp.
void QgsExpression::setGeomCalculator | ( | const QgsDistanceArea & | calc | ) |
Sets the geometry calculator used for distance and area calculations in expressions.
(used by $length, $area and $perimeter functions only). By default, no geometry calculator is set and all distance and area calculations are performed using simple cartesian methods (ie no ellipsoidal calculations).
Definition at line 3288 of file qgsexpression.cpp.
void QgsExpression::setScale | ( | double | scale | ) |
Definition at line 3106 of file qgsexpression.cpp.
Assign a special column.
Definition at line 3049 of file qgsexpression.cpp.
Return the value of the given special column or a null QVariant if undefined.
Definition at line 3069 of file qgsexpression.cpp.
|
static |
Returns a list of special Column definitions.
Definition at line 3118 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 2776 of file qgsexpression.cpp.
|
static |
Unset a special column.
Definition at line 3060 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 4572 of file qgsexpression.cpp.
|
friend |
Definition at line 1187 of file qgsexpression.h.
|
static |
Definition at line 422 of file qgsexpression.h.
|
protected |
Definition at line 1176 of file qgsexpression.h.
|
staticprotected |
Definition at line 1178 of file qgsexpression.h.
Definition at line 1180 of file qgsexpression.h.
|
static |
Definition at line 598 of file qgsexpression.h.
|
static |
Definition at line 594 of file qgsexpression.h.
|
static |
List of functions owned by the expression engine.
Definition at line 617 of file qgsexpression.h.
Definition at line 1098 of file qgsexpression.h.
Definition at line 1097 of file qgsexpression.h.
Definition at line 1179 of file qgsexpression.h.
|
static |
Definition at line 425 of file qgsexpression.h.