QGIS API Documentation  3.15.0-Master (1d5bfb2cfe)
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 
104 class CORE_EXPORT QgsExpression
105 {
106  Q_DECLARE_TR_FUNCTIONS( QgsExpression )
107  public:
108 
113  struct CORE_EXPORT ParserError
114  {
116  {
117  Unknown = 0,
118  FunctionUnknown = 1,
119  FunctionWrongArgs = 2,
120  FunctionInvalidParams = 3,
121  FunctionNamedArgsError = 4
122  };
123 
127  ParserErrorType errorType = ParserErrorType::Unknown;
128 
132  QString errorMsg;
133 
138  int firstLine = 0;
139 
144  int firstColumn = 0;
145 
149  int lastLine = 0;
150 
154  int lastColumn = 0;
155  };
156 
163  QgsExpression( const QString &expr );
164 
170  QgsExpression( const QgsExpression &other );
171 
177  QgsExpression &operator=( const QgsExpression &other );
178 
184  operator QString() const SIP_SKIP;
185 
191  QgsExpression();
192 
193  ~QgsExpression();
194 
201  bool operator==( const QgsExpression &other ) const;
202 
209  bool isValid() const;
210 
212  bool hasParserError() const;
214  QString parserErrorString() const;
215 
220  QList<QgsExpression::ParserError> parserErrors() const;
221 
227  const QgsExpressionNode *rootNode() const;
228 
234  bool prepare( const QgsExpressionContext *context );
235 
245  QSet<QString> referencedColumns() const;
246 
254  QSet<QString> referencedVariables() const;
255 
261  QSet<QString> referencedFunctions() const;
262 
263 #ifndef SIP_RUN
264 
271  QList<const QgsExpressionNode *> nodes( ) const;
272 
279  template <class T>
280  QList<const T *> findNodes( ) const
281  {
282  QList<const T *> lst;
283  const QList<const QgsExpressionNode *> allNodes( nodes() );
284  for ( const auto &node : allNodes )
285  {
286  const T *n = dynamic_cast<const T *>( node );
287  if ( n )
288  lst << n;
289  }
290  return lst;
291  }
292 #endif
293 
299  QSet<int> referencedAttributeIndexes( const QgsFields &fields ) const;
300 
302  bool needsGeometry() const;
303 
304  // evaluation
305 
311  QVariant evaluate();
312 
319  QVariant evaluate( const QgsExpressionContext *context );
320 
322  bool hasEvalError() const;
324  QString evalErrorString() const;
326  void setEvalErrorString( const QString &str );
327 
332  bool isField() const;
333 
342  static bool checkExpression( const QString &text, const QgsExpressionContext *context, QString &errorMessage SIP_OUT );
343 
349  void setExpression( const QString &expression );
350 
356  QString expression() const;
357 
364  QString dump() const;
365 
373  QgsDistanceArea *geomCalculator();
374 
388  void setGeomCalculator( const QgsDistanceArea *calc );
389 
397  QgsUnitTypes::DistanceUnit distanceUnits() const;
398 
408  void setDistanceUnits( QgsUnitTypes::DistanceUnit unit );
409 
417  QgsUnitTypes::AreaUnit areaUnits() const;
418 
428  void setAreaUnits( QgsUnitTypes::AreaUnit unit );
429 
441  static QString replaceExpressionText( const QString &action, const QgsExpressionContext *context,
442  const QgsDistanceArea *distanceArea = nullptr );
443 
451  static QSet<QString> referencedVariables( const QString &text );
452 
463  static double evaluateToDouble( const QString &text, double fallbackValue );
464 
466  {
476  };
477 
478  static const QList<QgsExpressionFunction *> &Functions();
479 
480  static const QStringList &BuiltinFunctions();
481 
489  static bool registerFunction( QgsExpressionFunction *function, bool transferOwnership = false );
490 
496  static bool unregisterFunction( const QString &name );
497 
502  static void cleanRegisteredFunctions();
503 
505  static bool isFunctionName( const QString &name );
506 
508  static int functionIndex( const QString &name );
509 
514  static int functionCount();
515 
521  static QString quotedColumnRef( QString name );
522 
528  static QString quotedString( QString text );
529 
538  static QString quotedValue( const QVariant &value );
539 
549  static QString quotedValue( const QVariant &value, QVariant::Type type );
550 
552 
559  static QString helpText( QString name );
560 
566  static QStringList tags( const QString &name );
567 
574  static QString variableHelpText( const QString &variableName );
575 
585  static QString formatVariableHelp( const QString &description, bool showValue = true, const QVariant &value = QVariant() );
586 
591  static QString group( const QString &group );
592 
601  static QString formatPreviewString( const QVariant &value, bool htmlOutput = true );
602 
611  static QString createFieldEqualityExpression( const QString &fieldName, const QVariant &value );
612 
613 #ifdef SIP_RUN
614  SIP_PYOBJECT __repr__();
615  % MethodCode
616  QString str = QStringLiteral( "<QgsExpression: '%1'>" ).arg( sipCpp->expression() );
617  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
618  % End
619 #endif
620 
621  private:
622  void initGeomCalculator( const QgsExpressionContext *context );
623 
630  void detach() SIP_SKIP;
631 
632  QgsExpressionPrivate *d = nullptr;
633 
635  static void initFunctionHelp() SIP_SKIP;
637  static void initVariableHelp() SIP_SKIP;
638 
639  friend class QgsOgcUtils;
640 };
641 
643 
644 #endif // QGSEXPRESSION_H
Class for parsing and evaluation of expressions (formerly called "search strings").
QString errorMsg
The message for the error at this location.
Details about any parser errors that were found when parsing the expression.
Container of fields for a vector layer.
Definition: qgsfields.h:44
A geometry is the spatial representation of a feature.
Definition: qgsgeometry.h:123
The feature class encapsulates a single feature including its id, geometry and a list of field/values...
Definition: qgsfeature.h:55
#define SIP_SKIP
Definition: qgis_sip.h:126
Expression contexts are used to encapsulate the parameters around which a QgsExpression should be eva...
Q_DECLARE_METATYPE(QgsMeshTimeSettings)
Abstract base class for all nodes that can appear in an expression.
Encapsulate a field in an attribute table or data source.
Definition: qgsfield.h:49
DistanceUnit
Units of distance.
Definition: qgsunittypes.h:67
A general purpose distance and area calculator, capable of performing ellipsoid based calculations...
A abstract base class for defining QgsExpression functions.
#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.
This is the base class for vector data providers.
Represents a vector layer which manages a vector based data sets.
QList< const T * > findNodes() const
Returns a list of all nodes of the given class which are used in this expression. ...
The QgsOgcUtils class provides various utility functions for conversion between OGC (Open Geospatial ...
Definition: qgsogcutils.h:50
AreaUnit
Units of area.
Definition: qgsunittypes.h:93