QGIS API Documentation  3.25.0-Master (dec16ba68b)
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 
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:125
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.