QGIS API Documentation  3.21.0-Master (5b68dc587e)
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 
34 class QgsFeature;
35 class QgsGeometry;
36 class QgsOgcUtils;
37 class QgsVectorLayer;
39 class QgsField;
40 class QgsFields;
41 class QgsDistanceArea;
42 class QDomElement;
44 class QgsExpressionPrivate;
46 
102 class 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 
189  QgsExpression();
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 
380  static bool checkExpression( const QString &text, const QgsExpressionContext *context, QString &errorMessage SIP_OUT );
381 
387  void setExpression( const QString &expression );
388 
394  QString expression() const;
395 
402  QString dump() const;
403 
411  QgsDistanceArea *geomCalculator();
412 
426  void setGeomCalculator( const QgsDistanceArea *calc );
427 
435  QgsUnitTypes::DistanceUnit distanceUnits() const;
436 
446  void setDistanceUnits( QgsUnitTypes::DistanceUnit unit );
447 
455  QgsUnitTypes::AreaUnit areaUnits() const;
456 
466  void setAreaUnits( QgsUnitTypes::AreaUnit unit );
467 
479  static QString replaceExpressionText( const QString &action, const QgsExpressionContext *context,
480  const QgsDistanceArea *distanceArea = nullptr );
481 
489  static QSet<QString> referencedVariables( const QString &text );
490 
501  static double evaluateToDouble( const QString &text, double fallbackValue );
502 
504  {
514  };
515 
516  static const QList<QgsExpressionFunction *> &Functions();
517 
518  static const QStringList &BuiltinFunctions();
519 
527  static bool registerFunction( QgsExpressionFunction *function, bool transferOwnership = false );
528 
534  static bool unregisterFunction( const QString &name );
535 
540  static void cleanRegisteredFunctions();
541 
543  static bool isFunctionName( const QString &name );
544 
546  static int functionIndex( const QString &name );
547 
552  static int functionCount();
553 
559  static QString quotedColumnRef( QString name );
560 
566  static QString quotedString( QString text );
567 
576  static QString quotedValue( const QVariant &value );
577 
587  static QString quotedValue( const QVariant &value, QVariant::Type type );
588 
590 
597  static QString helpText( QString name );
598 
604  static QStringList tags( const QString &name );
605 
612  static QString variableHelpText( const QString &variableName );
613 
623  static QString formatVariableHelp( const QString &description, bool showValue = true, const QVariant &value = QVariant() );
624 
629  static QString group( const QString &group );
630 
640  static QString formatPreviewString( const QVariant &value, bool htmlOutput = true, int maximumPreviewLength = 60 );
641 
650  static QString createFieldEqualityExpression( const QString &fieldName, const QVariant &value );
651 
662  static bool isFieldEqualityExpression( const QString &expression, QString &field SIP_OUT, QVariant &value SIP_OUT );
663 
678  static bool attemptReduceToInClause( const QStringList &expressions, QString &result SIP_OUT );
679 
680 #ifdef SIP_RUN
681  SIP_PYOBJECT __repr__();
682  % MethodCode
683  QString str = QStringLiteral( "<QgsExpression: '%1'>" ).arg( sipCpp->expression() );
684  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
685  % End
686 #endif
687 
688  private:
689  void initGeomCalculator( const QgsExpressionContext *context );
690 
697  void detach() SIP_SKIP;
698 
699  QgsExpressionPrivate *d = nullptr;
700 
702  static void initFunctionHelp() SIP_SKIP;
704  static void initVariableHelp() SIP_SKIP;
705 
706  friend class QgsOgcUtils;
707 };
708 
710 
711 #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:124
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
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
Q_DECLARE_METATYPE(QgsMeshTimeSettings)
Details about any parser errors that were found when parsing the expression.
QString errorMsg
The message for the error at this location.