QGIS API Documentation 3.39.0-Master (e8f1b343c48)
Loading...
Searching...
No Matches
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 <QRecursiveMutex>
28
29#include <functional>
30
31#include "qgis.h"
32#include "qgsinterval.h"
33#include "qgsexpressionnode.h"
34
35class QgsFeature;
36class QgsGeometry;
37class QgsOgcUtils;
38class QgsVectorLayer;
40class QgsField;
41class QgsFields;
42class QgsDistanceArea;
43class QDomElement;
45class QgsExpressionPrivate;
47
48#ifndef SIP_RUN
50struct HelpArg
51{
52 HelpArg( const QString &arg, const QString &desc, bool descOnly = false, bool syntaxOnly = false,
53 bool optional = false, const QString &defaultVal = QString() )
54 : mArg( arg )
55 , mDescription( desc )
56 , mDescOnly( descOnly )
57 , mSyntaxOnly( syntaxOnly )
58 , mOptional( optional )
59 , mDefaultVal( defaultVal )
60 {}
61
62 QString mArg;
63 QString mDescription;
64 bool mDescOnly;
65 bool mSyntaxOnly;
66 bool mOptional;
67 QString mDefaultVal;
68};
69
70struct HelpExample
71{
72 HelpExample( const QString &expression, const QString &returns, const QString &note = QString() )
73 : mExpression( expression )
74 , mReturns( returns )
75 , mNote( note )
76 {}
77
78 QString mExpression;
79 QString mReturns;
80 QString mNote;
81};
82
83
84struct HelpVariant
85{
86 HelpVariant( const QString &name, const QString &description,
87 const QList<HelpArg> &arguments = QList<HelpArg>(),
88 bool variableLenArguments = false,
89 const QList<HelpExample> &examples = QList<HelpExample>(),
90 const QString &notes = QString(),
91 const QStringList &tags = QStringList() )
92 : mName( name )
93 , mDescription( description )
94 , mArguments( arguments )
95 , mVariableLenArguments( variableLenArguments )
96 , mExamples( examples )
97 , mNotes( notes )
98 , mTags( tags )
99 {}
100
101 QString mName;
102 QString mDescription;
103 QList<HelpArg> mArguments;
104 bool mVariableLenArguments;
105 QList<HelpExample> mExamples;
106 QString mNotes;
107 QStringList mTags;
108};
109
110
111struct Help
112{
113 Help() = default;
114
115 Help( const QString &name, const QString &type, const QString &description, const QList<HelpVariant> &variants )
116 : mName( name )
117 , mType( type )
118 , mDescription( description )
119 , mVariants( variants )
120 {}
121
122 QString mName;
123 QString mType;
124 QString mDescription;
125 QList<HelpVariant> mVariants;
126};
127
128typedef QHash<QString, Help> HelpTextHash;
129
131#endif
132
188class CORE_EXPORT QgsExpression
189{
190 Q_DECLARE_TR_FUNCTIONS( QgsExpression )
191 public:
192
196 struct CORE_EXPORT ParserError
197 {
199 {
200 Unknown = 0,
201 FunctionUnknown = 1,
202 FunctionWrongArgs = 2,
203 FunctionInvalidParams = 3,
204 FunctionNamedArgsError = 4
205 };
206
210 ParserErrorType errorType = ParserErrorType::Unknown;
211
215 QString errorMsg;
216
221 int firstLine = 0;
222
227 int firstColumn = 0;
228
232 int lastLine = 0;
233
237 int lastColumn = 0;
238 };
239
246 QgsExpression( const QString &expr );
247
253 QgsExpression( const QgsExpression &other );
254
260 QgsExpression &operator=( const QgsExpression &other );
261
266 operator QString() const SIP_SKIP;
267
273
274 ~QgsExpression();
275
281 bool operator==( const QgsExpression &other ) const;
282
288 bool isValid() const;
289
291 bool hasParserError() const;
293 QString parserErrorString() const;
294
298 QList<QgsExpression::ParserError> parserErrors() const;
299
305 const QgsExpressionNode *rootNode() const;
306
311 bool prepare( const QgsExpressionContext *context );
312
330 QSet<QString> referencedColumns() const;
331
342 QSet<QString> referencedVariables() const;
343
353 QSet<QString> referencedFunctions() const;
354
355#ifndef SIP_RUN
356
363 QList<const QgsExpressionNode *> nodes( ) const;
364
371 template <class T>
372 QList<const T *> findNodes( ) const
373 {
374 QList<const T *> lst;
375 const QList<const QgsExpressionNode *> allNodes( nodes() );
376 for ( const auto &node : allNodes )
377 {
378 const T *n = dynamic_cast<const T *>( node );
379 if ( n )
380 lst << n;
381 }
382 return lst;
383 }
384#endif
385
398 QSet<int> referencedAttributeIndexes( const QgsFields &fields ) const;
399
401 bool needsGeometry() const;
402
403 // evaluation
404
409 QVariant evaluate();
410
416 QVariant evaluate( const QgsExpressionContext *context );
417
419 bool hasEvalError() const;
421 QString evalErrorString() const;
423 void setEvalErrorString( const QString &str );
424
430 bool isField() const;
431
444 static int expressionToLayerFieldIndex( const QString &expression, const QgsVectorLayer *layer );
445
458 static QString quoteFieldExpression( const QString &expression, const QgsVectorLayer *layer );
459
467 static bool checkExpression( const QString &text, const QgsExpressionContext *context, QString &errorMessage SIP_OUT );
468
473 void setExpression( const QString &expression );
474
480 QString expression() const;
481
488 QString dump() const;
489
497 QgsDistanceArea *geomCalculator();
498
512 void setGeomCalculator( const QgsDistanceArea *calc );
513
520 Qgis::DistanceUnit distanceUnits() const;
521
530 void setDistanceUnits( Qgis::DistanceUnit unit );
531
538 Qgis::AreaUnit areaUnits() const;
539
548 void setAreaUnits( Qgis::AreaUnit unit );
549
560 static QString replaceExpressionText( const QString &action, const QgsExpressionContext *context,
561 const QgsDistanceArea *distanceArea = nullptr );
562
570 static QSet<QString> referencedVariables( const QString &text );
571
581 static double evaluateToDouble( const QString &text, double fallbackValue );
582
595
596 static const QList<QgsExpressionFunction *> &Functions();
597
598 static const QStringList &BuiltinFunctions();
599
607 static bool registerFunction( QgsExpressionFunction *function, bool transferOwnership = false );
608
614 static bool unregisterFunction( const QString &name );
615
619 static void cleanRegisteredFunctions();
620
622 static bool isFunctionName( const QString &name );
623
625 static int functionIndex( const QString &name );
626
631 static int functionCount();
632
638 static QString quotedColumnRef( QString name );
639
645 static QString quotedString( QString text );
646
654 static QString quotedValue( const QVariant &value );
655
664 static QString quotedValue( const QVariant &value, QMetaType::Type type );
665
675 Q_DECL_DEPRECATED static QString quotedValue( const QVariant &value, QVariant::Type type ) SIP_DEPRECATED;
676
678
679#ifndef SIP_RUN
681 static HelpTextHash &functionHelpTexts();
683#endif
684
691 static QString helpText( QString name );
692
698 static QStringList tags( const QString &name );
699
712 static bool addVariableHelpText( const QString name, const QString &description );
713
720 static QString variableHelpText( const QString &variableName );
721
730 static QString formatVariableHelp( const QString &description, bool showValue = true, const QVariant &value = QVariant() );
731
736 static QString group( const QString &group );
737
746 static QString formatPreviewString( const QVariant &value, bool htmlOutput = true, int maximumPreviewLength = 60 );
747
756 static QString createFieldEqualityExpression( const QString &fieldName, const QVariant &value, QMetaType::Type fieldType = QMetaType::Type::UnknownType );
757
767 Q_DECL_DEPRECATED static QString createFieldEqualityExpression( const QString &fieldName, const QVariant &value, QVariant::Type fieldType ) SIP_DEPRECATED;
768
779 static bool isFieldEqualityExpression( const QString &expression, QString &field SIP_OUT, QVariant &value SIP_OUT );
780
795 static bool attemptReduceToInClause( const QStringList &expressions, QString &result SIP_OUT );
796
797#ifdef SIP_RUN
798 SIP_PYOBJECT __repr__();
799 % MethodCode
800 QString str = QStringLiteral( "<QgsExpression: '%1'>" ).arg( sipCpp->expression() );
801 sipRes = PyUnicode_FromString( str.toUtf8().constData() );
802 % End
803#endif
804
805 private:
806 void initGeomCalculator( const QgsExpressionContext *context );
807
814 void detach() SIP_SKIP;
815
816 QgsExpressionPrivate *d = nullptr;
817
818 static HelpTextHash sFunctionHelpTexts;
819
821 static void initFunctionHelp() SIP_SKIP;
823 static void initVariableHelp() SIP_SKIP;
824
826 static QRecursiveMutex sFunctionsMutex;
827 static QMap< QString, int> sFunctionIndexMap;
828
829 friend class QgsOgcUtils;
830};
831
833
834#endif // QGSEXPRESSION_H
DistanceUnit
Units of distance.
Definition qgis.h:4649
AreaUnit
Units of area.
Definition qgis.h:4726
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.
An expression node for expression 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:58
Encapsulate a field in an attribute table or data source.
Definition qgsfield.h:53
Container of fields for a vector layer.
Definition qgsfields.h:46
A geometry is the spatial representation of a feature.
The QgsOgcUtils class provides various utility functions for conversion between OGC (Open Geospatial ...
Definition qgsogcutils.h:54
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:38
#define SIP_DEPRECATED
Definition qgis_sip.h:106
#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.
Details about any parser errors that were found when parsing the expression.
QString errorMsg
The message for the error at this location.