QGIS API Documentation 3.29.0-Master (8c80f25a4f)
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 "qgsunittypes.h"
31#include "qgsinterval.h"
32#include "qgsexpressionnode.h"
33
34class QgsFeature;
35class QgsGeometry;
36class QgsOgcUtils;
37class QgsVectorLayer;
39class QgsField;
40class QgsFields;
41class QgsDistanceArea;
42class QDomElement;
44class QgsExpressionPrivate;
46
102class CORE_EXPORT QgsExpression
103{
104 Q_DECLARE_TR_FUNCTIONS( QgsExpression )
105 public:
106
111 struct CORE_EXPORT ParserError
112 {
114 {
115 Unknown = 0,
116 FunctionUnknown = 1,
117 FunctionWrongArgs = 2,
118 FunctionInvalidParams = 3,
119 FunctionNamedArgsError = 4
120 };
121
125 ParserErrorType errorType = ParserErrorType::Unknown;
126
130 QString errorMsg;
131
136 int firstLine = 0;
137
142 int firstColumn = 0;
143
147 int lastLine = 0;
148
152 int lastColumn = 0;
153 };
154
161 QgsExpression( const QString &expr );
162
168 QgsExpression( const QgsExpression &other );
169
175 QgsExpression &operator=( const QgsExpression &other );
176
182 operator QString() const SIP_SKIP;
183
190
191 ~QgsExpression();
192
199 bool operator==( const QgsExpression &other ) const;
200
207 bool isValid() const;
208
210 bool hasParserError() const;
212 QString parserErrorString() const;
213
218 QList<QgsExpression::ParserError> parserErrors() const;
219
225 const QgsExpressionNode *rootNode() const;
226
232 bool prepare( const QgsExpressionContext *context );
233
251 QSet<QString> referencedColumns() const;
252
264 QSet<QString> referencedVariables() const;
265
275 QSet<QString> referencedFunctions() const;
276
277#ifndef SIP_RUN
278
285 QList<const QgsExpressionNode *> nodes( ) const;
286
293 template <class T>
294 QList<const T *> findNodes( ) const
295 {
296 QList<const T *> lst;
297 const QList<const QgsExpressionNode *> allNodes( nodes() );
298 for ( const auto &node : allNodes )
299 {
300 const T *n = dynamic_cast<const T *>( node );
301 if ( n )
302 lst << n;
303 }
304 return lst;
305 }
306#endif
307
321 QSet<int> referencedAttributeIndexes( const QgsFields &fields ) const;
322
324 bool needsGeometry() const;
325
326 // evaluation
327
333 QVariant evaluate();
334
341 QVariant evaluate( const QgsExpressionContext *context );
342
344 bool hasEvalError() const;
346 QString evalErrorString() const;
348 void setEvalErrorString( const QString &str );
349
356 bool isField() const;
357
370 static int expressionToLayerFieldIndex( const QString &expression, const QgsVectorLayer *layer );
371
384 static QString quoteFieldExpression( const QString &expression, const QgsVectorLayer *layer );
385
394 static bool checkExpression( const QString &text, const QgsExpressionContext *context, QString &errorMessage SIP_OUT );
395
401 void setExpression( const QString &expression );
402
408 QString expression() const;
409
416 QString dump() const;
417
425 QgsDistanceArea *geomCalculator();
426
440 void setGeomCalculator( const QgsDistanceArea *calc );
441
449 QgsUnitTypes::DistanceUnit distanceUnits() const;
450
460 void setDistanceUnits( QgsUnitTypes::DistanceUnit unit );
461
469 QgsUnitTypes::AreaUnit areaUnits() const;
470
480 void setAreaUnits( QgsUnitTypes::AreaUnit unit );
481
493 static QString replaceExpressionText( const QString &action, const QgsExpressionContext *context,
494 const QgsDistanceArea *distanceArea = nullptr );
495
503 static QSet<QString> referencedVariables( const QString &text );
504
515 static double evaluateToDouble( const QString &text, double fallbackValue );
516
518 {
528 };
529
530 static const QList<QgsExpressionFunction *> &Functions();
531
532 static const QStringList &BuiltinFunctions();
533
541 static bool registerFunction( QgsExpressionFunction *function, bool transferOwnership = false );
542
548 static bool unregisterFunction( const QString &name );
549
554 static void cleanRegisteredFunctions();
555
557 static bool isFunctionName( const QString &name );
558
560 static int functionIndex( const QString &name );
561
566 static int functionCount();
567
573 static QString quotedColumnRef( QString name );
574
580 static QString quotedString( QString text );
581
590 static QString quotedValue( const QVariant &value );
591
601 static QString quotedValue( const QVariant &value, QVariant::Type type );
602
604
611 static QString helpText( QString name );
612
618 static QStringList tags( const QString &name );
619
632 static bool addVariableHelpText( const QString name, const QString &description );
633
641 static QString variableHelpText( const QString &variableName );
642
652 static QString formatVariableHelp( const QString &description, bool showValue = true, const QVariant &value = QVariant() );
653
658 static QString group( const QString &group );
659
669 static QString formatPreviewString( const QVariant &value, bool htmlOutput = true, int maximumPreviewLength = 60 );
670
680 static QString createFieldEqualityExpression( const QString &fieldName, const QVariant &value, QVariant::Type fieldType = QVariant::Type::Invalid );
681
692 static bool isFieldEqualityExpression( const QString &expression, QString &field SIP_OUT, QVariant &value SIP_OUT );
693
708 static bool attemptReduceToInClause( const QStringList &expressions, QString &result SIP_OUT );
709
710#ifdef SIP_RUN
711 SIP_PYOBJECT __repr__();
712 % MethodCode
713 QString str = QStringLiteral( "<QgsExpression: '%1'>" ).arg( sipCpp->expression() );
714 sipRes = PyUnicode_FromString( str.toUtf8().constData() );
715 % End
716#endif
717
718 private:
719 void initGeomCalculator( const QgsExpressionContext *context );
720
727 void detach() SIP_SKIP;
728
729 QgsExpressionPrivate *d = nullptr;
730
732 static void initFunctionHelp() SIP_SKIP;
734 static void initVariableHelp() SIP_SKIP;
735
736 friend class QgsOgcUtils;
737};
738
740
741#endif // QGSEXPRESSION_H
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:51
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
DistanceUnit
Units of distance.
Definition: qgsunittypes.h:68
AreaUnit
Units of area.
Definition: qgsunittypes.h:94
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:463
Details about any parser errors that were found when parsing the expression.
QString errorMsg
The message for the error at this location.