QGIS API Documentation  3.19.0-Master (f616be29d3)
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 
354  bool isField() const;
355 
364  static bool checkExpression( const QString &text, const QgsExpressionContext *context, QString &errorMessage SIP_OUT );
365 
371  void setExpression( const QString &expression );
372 
378  QString expression() const;
379 
386  QString dump() const;
387 
395  QgsDistanceArea *geomCalculator();
396 
410  void setGeomCalculator( const QgsDistanceArea *calc );
411 
419  QgsUnitTypes::DistanceUnit distanceUnits() const;
420 
430  void setDistanceUnits( QgsUnitTypes::DistanceUnit unit );
431 
439  QgsUnitTypes::AreaUnit areaUnits() const;
440 
450  void setAreaUnits( QgsUnitTypes::AreaUnit unit );
451 
463  static QString replaceExpressionText( const QString &action, const QgsExpressionContext *context,
464  const QgsDistanceArea *distanceArea = nullptr );
465 
473  static QSet<QString> referencedVariables( const QString &text );
474 
485  static double evaluateToDouble( const QString &text, double fallbackValue );
486 
488  {
498  };
499 
500  static const QList<QgsExpressionFunction *> &Functions();
501 
502  static const QStringList &BuiltinFunctions();
503 
511  static bool registerFunction( QgsExpressionFunction *function, bool transferOwnership = false );
512 
518  static bool unregisterFunction( const QString &name );
519 
524  static void cleanRegisteredFunctions();
525 
527  static bool isFunctionName( const QString &name );
528 
530  static int functionIndex( const QString &name );
531 
536  static int functionCount();
537 
543  static QString quotedColumnRef( QString name );
544 
550  static QString quotedString( QString text );
551 
560  static QString quotedValue( const QVariant &value );
561 
571  static QString quotedValue( const QVariant &value, QVariant::Type type );
572 
574 
581  static QString helpText( QString name );
582 
588  static QStringList tags( const QString &name );
589 
596  static QString variableHelpText( const QString &variableName );
597 
607  static QString formatVariableHelp( const QString &description, bool showValue = true, const QVariant &value = QVariant() );
608 
613  static QString group( const QString &group );
614 
624  static QString formatPreviewString( const QVariant &value, bool htmlOutput = true, int maximumPreviewLength = 60 );
625 
634  static QString createFieldEqualityExpression( const QString &fieldName, const QVariant &value );
635 
646  static bool isFieldEqualityExpression( const QString &expression, QString &field SIP_OUT, QVariant &value SIP_OUT );
647 
662  static bool attemptReduceToInClause( const QStringList &expressions, QString &result SIP_OUT );
663 
664 #ifdef SIP_RUN
665  SIP_PYOBJECT __repr__();
666  % MethodCode
667  QString str = QStringLiteral( "<QgsExpression: '%1'>" ).arg( sipCpp->expression() );
668  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
669  % End
670 #endif
671 
672  private:
673  void initGeomCalculator( const QgsExpressionContext *context );
674 
681  void detach() SIP_SKIP;
682 
683  QgsExpressionPrivate *d = nullptr;
684 
686  static void initFunctionHelp() SIP_SKIP;
688  static void initVariableHelp() SIP_SKIP;
689 
690  friend class QgsOgcUtils;
691 };
692 
694 
695 #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 id, geometry and a list of field/values...
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:51
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.