QGIS API Documentation 3.31.0-Master (d2b117a3c8)
qgsexpression.h
Go to the documentation of this file.
1/***************************************************************************
2 qgsexpression.h
3 -------------------
4 begin : August 2011
5 copyright : (C) 2011 Martin Dobias
6 email : wonder.sk at gmail dot com
7 ***************************************************************************
8 * *
9 * This program is free software; you can redistribute it and/or modify *
10 * it under the terms of the GNU General Public License as published by *
11 * the Free Software Foundation; either version 2 of the License, or *
12 * (at your option) any later version. *
13 * *
14 ***************************************************************************/
15
16#ifndef QGSEXPRESSION_H
17#define QGSEXPRESSION_H
18
19#include "qgis_core.h"
20#include <QMetaType>
21#include <QStringList>
22#include <QVariant>
23#include <QList>
24#include <QDomDocument>
25#include <QCoreApplication>
26#include <QSet>
27#include <functional>
28
29#include "qgis.h"
30#include "qgsinterval.h"
31#include "qgsexpressionnode.h"
32
33class QgsFeature;
34class QgsGeometry;
35class QgsOgcUtils;
36class QgsVectorLayer;
38class QgsField;
39class QgsFields;
40class QgsDistanceArea;
41class QDomElement;
43class QgsExpressionPrivate;
45
101class CORE_EXPORT QgsExpression
102{
103 Q_DECLARE_TR_FUNCTIONS( QgsExpression )
104 public:
105
110 struct CORE_EXPORT ParserError
111 {
113 {
114 Unknown = 0,
115 FunctionUnknown = 1,
116 FunctionWrongArgs = 2,
117 FunctionInvalidParams = 3,
118 FunctionNamedArgsError = 4
119 };
120
124 ParserErrorType errorType = ParserErrorType::Unknown;
125
129 QString errorMsg;
130
135 int firstLine = 0;
136
141 int firstColumn = 0;
142
146 int lastLine = 0;
147
151 int lastColumn = 0;
152 };
153
160 QgsExpression( const QString &expr );
161
167 QgsExpression( const QgsExpression &other );
168
174 QgsExpression &operator=( const QgsExpression &other );
175
181 operator QString() const SIP_SKIP;
182
189
190 ~QgsExpression();
191
198 bool operator==( const QgsExpression &other ) const;
199
206 bool isValid() const;
207
209 bool hasParserError() const;
211 QString parserErrorString() const;
212
217 QList<QgsExpression::ParserError> parserErrors() const;
218
224 const QgsExpressionNode *rootNode() const;
225
231 bool prepare( const QgsExpressionContext *context );
232
250 QSet<QString> referencedColumns() const;
251
263 QSet<QString> referencedVariables() const;
264
274 QSet<QString> referencedFunctions() const;
275
276#ifndef SIP_RUN
277
284 QList<const QgsExpressionNode *> nodes( ) const;
285
292 template <class T>
293 QList<const T *> findNodes( ) const
294 {
295 QList<const T *> lst;
296 const QList<const QgsExpressionNode *> allNodes( nodes() );
297 for ( const auto &node : allNodes )
298 {
299 const T *n = dynamic_cast<const T *>( node );
300 if ( n )
301 lst << n;
302 }
303 return lst;
304 }
305#endif
306
320 QSet<int> referencedAttributeIndexes( const QgsFields &fields ) const;
321
323 bool needsGeometry() const;
324
325 // evaluation
326
332 QVariant evaluate();
333
340 QVariant evaluate( const QgsExpressionContext *context );
341
343 bool hasEvalError() const;
345 QString evalErrorString() const;
347 void setEvalErrorString( const QString &str );
348
355 bool isField() const;
356
369 static int expressionToLayerFieldIndex( const QString &expression, const QgsVectorLayer *layer );
370
383 static QString quoteFieldExpression( const QString &expression, const QgsVectorLayer *layer );
384
393 static bool checkExpression( const QString &text, const QgsExpressionContext *context, QString &errorMessage SIP_OUT );
394
400 void setExpression( const QString &expression );
401
407 QString expression() const;
408
415 QString dump() const;
416
424 QgsDistanceArea *geomCalculator();
425
439 void setGeomCalculator( const QgsDistanceArea *calc );
440
448 Qgis::DistanceUnit distanceUnits() const;
449
459 void setDistanceUnits( Qgis::DistanceUnit unit );
460
468 Qgis::AreaUnit areaUnits() const;
469
479 void setAreaUnits( Qgis::AreaUnit unit );
480
492 static QString replaceExpressionText( const QString &action, const QgsExpressionContext *context,
493 const QgsDistanceArea *distanceArea = nullptr );
494
502 static QSet<QString> referencedVariables( const QString &text );
503
514 static double evaluateToDouble( const QString &text, double fallbackValue );
515
517 {
527 };
528
529 static const QList<QgsExpressionFunction *> &Functions();
530
531 static const QStringList &BuiltinFunctions();
532
540 static bool registerFunction( QgsExpressionFunction *function, bool transferOwnership = false );
541
547 static bool unregisterFunction( const QString &name );
548
553 static void cleanRegisteredFunctions();
554
556 static bool isFunctionName( const QString &name );
557
559 static int functionIndex( const QString &name );
560
565 static int functionCount();
566
572 static QString quotedColumnRef( QString name );
573
579 static QString quotedString( QString text );
580
589 static QString quotedValue( const QVariant &value );
590
600 static QString quotedValue( const QVariant &value, QVariant::Type type );
601
603
610 static QString helpText( QString name );
611
617 static QStringList tags( const QString &name );
618
631 static bool addVariableHelpText( const QString name, const QString &description );
632
640 static QString variableHelpText( const QString &variableName );
641
651 static QString formatVariableHelp( const QString &description, bool showValue = true, const QVariant &value = QVariant() );
652
657 static QString group( const QString &group );
658
668 static QString formatPreviewString( const QVariant &value, bool htmlOutput = true, int maximumPreviewLength = 60 );
669
679 static QString createFieldEqualityExpression( const QString &fieldName, const QVariant &value, QVariant::Type fieldType = QVariant::Type::Invalid );
680
691 static bool isFieldEqualityExpression( const QString &expression, QString &field SIP_OUT, QVariant &value SIP_OUT );
692
707 static bool attemptReduceToInClause( const QStringList &expressions, QString &result SIP_OUT );
708
709#ifdef SIP_RUN
710 SIP_PYOBJECT __repr__();
711 % MethodCode
712 QString str = QStringLiteral( "<QgsExpression: '%1'>" ).arg( sipCpp->expression() );
713 sipRes = PyUnicode_FromString( str.toUtf8().constData() );
714 % End
715#endif
716
717 private:
718 void initGeomCalculator( const QgsExpressionContext *context );
719
726 void detach() SIP_SKIP;
727
728 QgsExpressionPrivate *d = nullptr;
729
731 static void initFunctionHelp() SIP_SKIP;
733 static void initVariableHelp() SIP_SKIP;
734
735 friend class QgsOgcUtils;
736};
737
739
740#endif // QGSEXPRESSION_H
DistanceUnit
Units of distance.
Definition: qgis.h:3083
AreaUnit
Units of area.
Definition: qgis.h:3120
A general purpose distance and area calculator, capable of performing ellipsoid based calculations.
Expression contexts are used to encapsulate the parameters around which a QgsExpression should be eva...
A abstract base class for defining QgsExpression functions.
Abstract base class for all nodes that can appear in an expression.
Class for parsing and evaluation of expressions (formerly called "search strings").
QList< const T * > findNodes() const
Returns a list of all nodes of the given class which are used in this expression.
The feature class encapsulates a single feature including its unique ID, geometry and a list of field...
Definition: qgsfeature.h:56
Encapsulate a field in an attribute table or data source.
Definition: qgsfield.h:53
Container of fields for a vector layer.
Definition: qgsfields.h:45
A geometry is the spatial representation of a feature.
Definition: qgsgeometry.h:164
The QgsOgcUtils class provides various utility functions for conversion between OGC (Open Geospatial ...
Definition: qgsogcutils.h:52
This is the base class for vector data providers.
Represents a vector layer which manages a vector based data sets.
#define str(x)
Definition: qgis.cpp:37
#define SIP_SKIP
Definition: qgis_sip.h:126
#define SIP_OUT
Definition: qgis_sip.h:58
Q_DECLARE_METATYPE(QgsDatabaseQueryLogEntry)
QString formatVariableHelp(const QString &variable, const QString &description, bool showValue, const QVariant &value)
Returns a HTML formatted string for use as a variable item help.
const QgsField & field
Definition: qgsfield.h:554
Details about any parser errors that were found when parsing the expression.
QString errorMsg
The message for the error at this location.