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

Inheritance diagram for QgsExpression:
Inheritance graph
[legend]

Classes

class  Function
 A abstract base class for defining QgsExpression functions. More...
 
struct  Help
 
struct  HelpArg
 
struct  HelpExample
 
struct  HelpVariant
 
class  Interval
 
class  NamedNode
 Named node. More...
 
class  Node
 
class  NodeBinaryOperator
 
class  NodeColumnRef
 
class  NodeCondition
 
class  NodeFunction
 
class  NodeInOperator
 
class  NodeList
 
class  NodeLiteral
 
class  NodeUnaryOperator
 
class  Parameter
 Represents a single parameter passed to a function. More...
 
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, using a list of values as parameters to the function. More...
 
enum  NodeType {
  ntUnaryOperator, ntBinaryOperator, ntInOperator, ntFunction,
  ntLiteral, ntColumnRef, ntCondition
}
 
typedef QList< ParameterParameterList
 List of parameters, used for function definition. More...
 
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...
 
QgsDistanceAreageomCalculator ()
 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...
 
QgsExpressionoperator= (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 NoderootNode () 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 QStringListBuiltinFunctions ()
 
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, HelpgFunctionHelpTexts
 
static QHash< QString, QStringgGroups
 
static QMap< QString, QStringgmSpecialColumnGroups
 
static QMap< QString, QVariantgmSpecialColumns
 
static QHash< QString, QStringgVariableHelpTexts
 

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
}

Three Value Logic

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.

Performance

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 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.

Implicit sharing

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

Member Typedef Documentation

typedef QVariant( * QgsExpression::FcnEval) (const QVariantList &values, const QgsFeature *f, QgsExpression *parent)
Deprecated:
will be removed in QGIS 3.0

Definition at line 473 of file qgsexpression.h.

typedef QVariant( * QgsExpression::FcnEvalContext) (const QVariantList &values, const QgsExpressionContext *context, QgsExpression *parent)

Function definition for evaluation against an expression context, using a list of values as parameters to the function.

Definition at line 477 of file qgsexpression.h.

List of parameters, used for function definition.

Definition at line 470 of file qgsexpression.h.

Definition at line 1286 of file qgsexpression.h.

Member Enumeration Documentation

list of binary operators

Note
if any change is made here, the definition of QgsExpression::BinaryOperatorText[] must be adapted.
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 375 of file qgsexpression.h.

Enumerator
ntUnaryOperator 
ntBinaryOperator 
ntInOperator 
ntFunction 
ntLiteral 
ntColumnRef 
ntCondition 

Definition at line 791 of file qgsexpression.h.

Enumerator
soBbox 
soIntersects 
soContains 
soCrosses 
soEquals 
soDisjoint 
soOverlaps 
soTouches 
soWithin 

Definition at line 409 of file qgsexpression.h.

list of unary operators

Note
if any change is made here, the definition of QgsExpression::UnaryOperatorText[] must be adapted.
Enumerator
uoNot 
uoMinus 

Definition at line 365 of file qgsexpression.h.

Constructor & Destructor Documentation

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

QgsExpression::~QgsExpression ( )

Definition at line 3257 of file qgsexpression.cpp.

QgsExpression::QgsExpression ( )
protected

Used by QgsOgcUtils to create an empty.

Definition at line 3252 of file qgsexpression.cpp.

Member Function Documentation

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

Entry function for the visitor pattern.

Definition at line 3472 of file qgsexpression.cpp.

QgsUnitTypes::AreaUnit QgsExpression::areaUnits ( ) const

Returns the desired areal units for calculations involving geomCalculator(), eg "$area".

Note
areas are only converted when a geomCalculator() has been set
added in QGIS 2.14
See also
setAreaUnits()
distanceUnits()

Definition at line 3462 of file qgsexpression.cpp.

const QStringList & QgsExpression::BuiltinFunctions ( )
static

Definition at line 2825 of file qgsexpression.cpp.

void QgsExpression::cleanRegisteredFunctions ( )
static

Deletes all registered functions whose ownership have been transferred to the expression engine.

Note
added in QGIS 2.12

Definition at line 2817 of file qgsexpression.cpp.

int QgsExpression::currentRowNumber ( )

Return the number used for $rownum special column.

Deprecated:
use QgsExpressionContext to retrieve row number instead

Definition at line 3437 of file qgsexpression.cpp.

void QgsExpression::detach ( )
protected

Helper for implicit sharing.

When called will create a new deep copy of this expression.

Note
not available in Python bindings

Definition at line 3309 of file qgsexpression.cpp.

QGis::UnitType QgsExpression::distanceUnits ( ) const

Returns the desired distance units for calculations involving geomCalculator(), eg "$length" and "$perimeter".

Note
distances are only converted when a geomCalculator() has been set
added in QGIS 2.14
See also
setDistanceUnits()
areaUnits()

Definition at line 3452 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 3439 of file qgsexpression.cpp.

QString QgsExpression::evalErrorString ( ) const

Returns evaluation error.

Definition at line 3422 of file qgsexpression.cpp.

QVariant QgsExpression::evaluate ( const QgsFeature f)

Evaluate the feature and return the result.

Note
prepare() should be called before calling this method
Deprecated:
use evaluate( const QgsExpressionContext* context ) instead

Definition at line 3354 of file qgsexpression.cpp.

QVariant QgsExpression::evaluate ( const QgsFeature f)

Evaluate the feature and return the result.

Note
prepare() should be called before calling this method
available in python bindings as evaluatePrepared
Deprecated:
use evaluate( const QgsExpressionContext* context ) instead

Definition at line 3367 of file qgsexpression.cpp.

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
Deprecated:
use evaluate( const QgsExpressionContext* context ) instead

Definition at line 3374 of file qgsexpression.cpp.

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
not available in python bindings
Deprecated:
use evaluate( const QgsExpressionContext* context ) instead

Definition at line 3386 of file qgsexpression.cpp.

QVariant QgsExpression::evaluate ( )

Evaluate the feature and return the result.

Note
this method does not expect that prepare() has been called on this instance
added in QGIS 2.12

Definition at line 3393 of file qgsexpression.cpp.

QVariant QgsExpression::evaluate ( const QgsExpressionContext context)

Evaluate the expression against the specified context and return the result.

Parameters
contextcontext for evaluating expression
Note
prepare() should be called before calling this method.
added in QGIS 2.12

Definition at line 3405 of file qgsexpression.cpp.

double QgsExpression::evaluateToDouble ( const QString text,
const double  fallbackValue 
)
static

Attempts to evaluate a text string as an expression to a resultant double value.

Parameters
texttext to evaluate as expression
fallbackValuevalue to return if text can not be evaluated as a double
Returns
evaluated double value, or fallback value
Note
added in QGIS 2.7
this method is inefficient for bulk evaluation of expressions, it is intended for one-off evaluations only.

Definition at line 3561 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 3143 of file qgsexpression.cpp.

QString QgsExpression::formatPreviewString ( const QVariant value)
static

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).

Parameters
valueexpression result to format
Returns
formatted string, may contain HTML formatting characters
Note
added in QGIS 2.14

Definition at line 4659 of file qgsexpression.cpp.

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

int QgsExpression::functionIndex ( const QString name)
static

return index of the function in Functions array

Definition at line 3209 of file qgsexpression.cpp.

const QList< QgsExpression::Function * > & QgsExpression::Functions ( )
static

Definition at line 2878 of file qgsexpression.cpp.

QgsDistanceArea * QgsExpression::geomCalculator ( )

Return calculator used for distance and area calculations (used by $length, $area and $perimeter functions only)

See also
setGeomCalculator()
distanceUnits()
areaUnits()

Definition at line 3447 of file qgsexpression.cpp.

QString QgsExpression::group ( const QString group)
static

Returns the translated name for a function group.

Parameters
groupuntranslated group name

Definition at line 4633 of file qgsexpression.cpp.

bool QgsExpression::hasEvalError ( ) const

Returns true if an error occurred when evaluating last input.

Definition at line 3417 of file qgsexpression.cpp.

bool QgsExpression::hasParserError ( ) const

Returns true if an error occurred when parsing the input expression.

Definition at line 3264 of file qgsexpression.cpp.

bool QgsExpression::hasSpecialColumn ( const QString name)
static

Check whether a special column exists.

Note
added in 2.2

Definition at line 3118 of file qgsexpression.cpp.

QString QgsExpression::helptext ( QString  name)
static

Returns the help text for a specified function.

Parameters
namefunction name
See also
variableHelpText()

Definition at line 4422 of file qgsexpression.cpp.

static void QgsExpression::initFunctionHelp ( )
staticprotected
Note
not available in Python bindings
void QgsExpression::initGeomCalculator ( )
protected

Definition at line 3299 of file qgsexpression.cpp.

void QgsExpression::initVariableHelp ( )
staticprotected
Note
not available in Python bindings

Definition at line 4542 of file qgsexpression.cpp.

bool QgsExpression::isField ( ) const
inline

Checks whether an expression consists only of a single field reference.

Note
added in 2.9

Definition at line 239 of file qgsexpression.h.

bool QgsExpression::isFunctionName ( const QString name)
static

tells whether the identifier is a name of existing function

Definition at line 3204 of file qgsexpression.cpp.

bool QgsExpression::isValid ( const QString text,
const QgsFields fields,
QString errorMessage 
)
static
Deprecated:
use QgsExpressionContext variant instead

Definition at line 3125 of file qgsexpression.cpp.

bool QgsExpression::isValid ( const QString text,
const QgsExpressionContext context,
QString errorMessage 
)
static

Tests whether a string is a valid expression.

Parameters
textstring to test
contextoptional expression context
errorMessagewill be filled with any error message from the validation
Returns
true if string is a valid expression
Note
added in QGIS 2.12

Definition at line 3131 of file qgsexpression.cpp.

bool QgsExpression::needsGeometry ( ) const

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

Definition at line 3292 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 3245 of file qgsexpression.cpp.

QString QgsExpression::parserErrorString ( ) const

Returns parser error.

Definition at line 3266 of file qgsexpression.cpp.

bool QgsExpression::prepare ( const QgsFields fields)

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

Deprecated:
use prepare( const QgsExpressionContext *context ) instead

Definition at line 3326 of file qgsexpression.cpp.

bool QgsExpression::prepare ( const QgsExpressionContext context)

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

Parameters
contextcontext for preparing expression
Note
added in QGIS 2.12

Definition at line 3333 of file qgsexpression.cpp.

QString QgsExpression::quotedColumnRef ( QString  name)
static

Returns a quoted column reference (in double quotes)

See also
quotedString()
quotedValue()

Definition at line 3163 of file qgsexpression.cpp.

QString QgsExpression::quotedString ( QString  text)
static

Returns a quoted version of a string (in single quotes)

See also
quotedValue()
quotedColumnRef()

Definition at line 3168 of file qgsexpression.cpp.

QString QgsExpression::quotedValue ( const QVariant value)
static

Returns a string representation of a literal value, including appropriate quotations where required.

Parameters
valuevalue to convert to a string representation
Note
added in QGIS 2.14
See also
quotedString()
quotedColumnRef()

Definition at line 3177 of file qgsexpression.cpp.

QString QgsExpression::quotedValue ( const QVariant value,
QVariant::Type  type 
)
static

Returns a string representation of a literal value, including appropriate quotations where required.

Parameters
valuevalue to convert to a string representation
typevalue type
Note
added in QGIS 2.14
See also
quotedString()
quotedColumnRef()

Definition at line 3182 of file qgsexpression.cpp.

QStringList QgsExpression::referencedColumns ( ) const

Get list of columns referenced by the expression.

Note
if the returned list contains the QgsFeatureRequest::AllAttributes constant then all attributes from the layer are required for evaluation of the expression. QgsFeatureRequest::setSubsetOfAttributes automatically handles this case.

TODO QGIS3: Return QSet<QString>

Definition at line 3268 of file qgsexpression.cpp.

bool QgsExpression::registerFunction ( QgsExpression::Function function,
bool  transferOwnership = false 
)
static

Registers a function to the expression engine.

This is required to allow expressions to utilise the function.

Parameters
functionfunction to register
transferOwnershipset to true to transfer ownership of function to expression engine
Returns
true on successful registration
See also
unregisterFunction

Definition at line 2788 of file qgsexpression.cpp.

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

Parameters
action
feat
layer
substitutionMap
distanceAreaoptional QgsDistanceArea. If specified, the QgsDistanceArea is used for distance and area conversion
Deprecated:
use QgsExpressionContext variant instead

Definition at line 3478 of file qgsexpression.cpp.

QString QgsExpression::replaceExpressionText ( const QString action,
const QgsExpressionContext context,
const QMap< QString, QVariant > *  substitutionMap = nullptr,
const QgsDistanceArea distanceArea = nullptr 
)
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

Parameters
action
contextexpression context
substitutionMap
distanceAreaoptional QgsDistanceArea. If specified, the QgsDistanceArea is used for distance and area conversion
Note
added in QGIS 2.12

Definition at line 3486 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 4778 of file qgsexpression.cpp.

double QgsExpression::scale ( )

Definition at line 3141 of file qgsexpression.cpp.

void QgsExpression::setAreaUnits ( QgsUnitTypes::AreaUnit  unit)

Sets the desired areal units for calculations involving geomCalculator(), eg "$area".

Note
areas are only converted when a geomCalculator() has been set
added in QGIS 2.14
See also
areaUnits()
setDistanceUnits()

Definition at line 3467 of file qgsexpression.cpp.

void QgsExpression::setCurrentRowNumber ( int  rowNumber)

Set the number for $rownum special column.

Deprecated:
use QgsExpressionContext to set row number instead

Definition at line 3432 of file qgsexpression.cpp.

void QgsExpression::setDistanceUnits ( QGis::UnitType  unit)

Sets the desired distance units for calculations involving geomCalculator(), eg "$length" and "$perimeter".

Note
distances are only converted when a geomCalculator() has been set
added in QGIS 2.14
See also
distanceUnits()
setAreaUnits()

Definition at line 3457 of file qgsexpression.cpp.

void QgsExpression::setEvalErrorString ( const QString str)

Set evaluation error (used internally by evaluation functions)

Definition at line 3427 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).

See also
geomCalculator()

Definition at line 3321 of file qgsexpression.cpp.

void QgsExpression::setScale ( double  scale)

Definition at line 3139 of file qgsexpression.cpp.

void QgsExpression::setSpecialColumn ( const QString name,
const QVariant value 
)
static

Assign a special column.

Deprecated:
use global or project QgsExpressionContext variables instead

Definition at line 3082 of file qgsexpression.cpp.

QVariant QgsExpression::specialColumn ( const QString name)
static

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

Deprecated:
use global or project QgsExpressionContext variables instead

Definition at line 3102 of file qgsexpression.cpp.

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

Returns a list of special Column definitions.

Definition at line 3151 of file qgsexpression.cpp.

bool QgsExpression::unregisterFunction ( const QString name)
static

Unregisters a function from the expression engine.

The function will no longer be usable in expressions.

Parameters
namefunction name
See also
registerFunction

Definition at line 2801 of file qgsexpression.cpp.

void QgsExpression::unsetSpecialColumn ( const QString name)
static

Unset a special column.

Deprecated:
use global or project QgsExpressionContext variables instead

Definition at line 3093 of file qgsexpression.cpp.

QString QgsExpression::variableHelpText ( const QString variableName,
bool  showValue = true,
const QVariant value = QVariant() 
)
static

Returns the help text for a specified variable.

Parameters
variableNamename of variable
showValueset to true to include current value of variable in help text
valuecurrent value of variable to show in help text
See also
helptext()
Note
added in QGIS 2.12

Definition at line 4611 of file qgsexpression.cpp.

Friends And Related Function Documentation

friend class QgsOgcUtils
friend

Definition at line 1461 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",
"+", "-", "*", "/", "//", "%", "^",
"||"
}
Note
not available in Python bindings

Definition at line 423 of file qgsexpression.h.

QgsExpressionPrivate* QgsExpression::d
protected

Definition at line 1450 of file qgsexpression.h.

QHash<QString, Help> QgsExpression::gFunctionHelpTexts
staticprotected

Definition at line 1452 of file qgsexpression.h.

QHash< QString, QString > QgsExpression::gGroups
staticprotected

Definition at line 1454 of file qgsexpression.h.

QStringList QgsExpression::gmBuiltinFunctions
static
Note
not available in Python bindings

Definition at line 714 of file qgsexpression.h.

QList< QgsExpression::Function * > QgsExpression::gmFunctions
static
Note
not available in Python bindings

Definition at line 710 of file qgsexpression.h.

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

List of functions owned by the expression engine.

Note
not available in Python bindings

Definition at line 733 of file qgsexpression.h.

QMap< QString, QString > QgsExpression::gmSpecialColumnGroups
staticprotected

Definition at line 1367 of file qgsexpression.h.

QMap< QString, QVariant > QgsExpression::gmSpecialColumns
staticprotected

Definition at line 1366 of file qgsexpression.h.

QHash< QString, QString > QgsExpression::gVariableHelpTexts
staticprotected

Definition at line 1453 of file qgsexpression.h.

const char * QgsExpression::UnaryOperatorText
static
Initial value:
=
{
"NOT", "-"
}
Note
not available in Python bindings

Definition at line 426 of file qgsexpression.h.


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