QGIS API Documentation  3.15.0-Master (a49cb7c9f3)
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 
113 class CORE_EXPORT QgsExpression
114 {
115  Q_DECLARE_TR_FUNCTIONS( QgsExpression )
116  public:
117 
122  struct CORE_EXPORT ParserError
123  {
125  {
126  Unknown = 0,
127  FunctionUnknown = 1,
128  FunctionWrongArgs = 2,
129  FunctionInvalidParams = 3,
130  FunctionNamedArgsError = 4
131  };
132 
136  ParserErrorType errorType = ParserErrorType::Unknown;
137 
141  QString errorMsg;
142 
147  int firstLine = 0;
148 
153  int firstColumn = 0;
154 
158  int lastLine = 0;
159 
163  int lastColumn = 0;
164  };
165 
172  QgsExpression( const QString &expr );
173 
179  QgsExpression( const QgsExpression &other );
180 
186  QgsExpression &operator=( const QgsExpression &other );
187 
193  operator QString() const SIP_SKIP;
194 
200  QgsExpression();
201 
202  ~QgsExpression();
203 
210  bool operator==( const QgsExpression &other ) const;
211 
218  bool isValid() const;
219 
221  bool hasParserError() const;
223  QString parserErrorString() const;
224 
229  QList<QgsExpression::ParserError> parserErrors() const;
230 
236  const QgsExpressionNode *rootNode() const;
237 
243  bool prepare( const QgsExpressionContext *context );
244 
254  QSet<QString> referencedColumns() const;
255 
263  QSet<QString> referencedVariables() const;
264 
270  QSet<QString> referencedFunctions() const;
271 
272 #ifndef SIP_RUN
273 
280  QList<const QgsExpressionNode *> nodes( ) const;
281 
288  template <class T>
289  QList<const T *> findNodes( ) const
290  {
291  QList<const T *> lst;
292  const QList<const QgsExpressionNode *> allNodes( nodes() );
293  for ( const auto &node : allNodes )
294  {
295  const T *n = dynamic_cast<const T *>( node );
296  if ( n )
297  lst << n;
298  }
299  return lst;
300  }
301 #endif
302 
308  QSet<int> referencedAttributeIndexes( const QgsFields &fields ) const;
309 
311  bool needsGeometry() const;
312 
313  // evaluation
314 
320  QVariant evaluate();
321 
328  QVariant evaluate( const QgsExpressionContext *context );
329 
331  bool hasEvalError() const;
333  QString evalErrorString() const;
335  void setEvalErrorString( const QString &str );
336 
341  bool isField() const;
342 
351  static bool checkExpression( const QString &text, const QgsExpressionContext *context, QString &errorMessage SIP_OUT );
352 
358  void setExpression( const QString &expression );
359 
365  QString expression() const;
366 
373  QString dump() const;
374 
382  QgsDistanceArea *geomCalculator();
383 
397  void setGeomCalculator( const QgsDistanceArea *calc );
398 
406  QgsUnitTypes::DistanceUnit distanceUnits() const;
407 
417  void setDistanceUnits( QgsUnitTypes::DistanceUnit unit );
418 
426  QgsUnitTypes::AreaUnit areaUnits() const;
427 
437  void setAreaUnits( QgsUnitTypes::AreaUnit unit );
438 
450  static QString replaceExpressionText( const QString &action, const QgsExpressionContext *context,
451  const QgsDistanceArea *distanceArea = nullptr );
452 
460  static QSet<QString> referencedVariables( const QString &text );
461 
472  static double evaluateToDouble( const QString &text, double fallbackValue );
473 
475  {
485  };
486 
487  static const QList<QgsExpressionFunction *> &Functions();
488 
489  static const QStringList &BuiltinFunctions();
490 
498  static bool registerFunction( QgsExpressionFunction *function, bool transferOwnership = false );
499 
505  static bool unregisterFunction( const QString &name );
506 
511  static void cleanRegisteredFunctions();
512 
514  static bool isFunctionName( const QString &name );
515 
517  static int functionIndex( const QString &name );
518 
523  static int functionCount();
524 
530  static QString quotedColumnRef( QString name );
531 
537  static QString quotedString( QString text );
538 
547  static QString quotedValue( const QVariant &value );
548 
558  static QString quotedValue( const QVariant &value, QVariant::Type type );
559 
561 
568  static QString helpText( QString name );
569 
575  static QStringList tags( const QString &name );
576 
583  static QString variableHelpText( const QString &variableName );
584 
594  static QString formatVariableHelp( const QString &description, bool showValue = true, const QVariant &value = QVariant() );
595 
600  static QString group( const QString &group );
601 
610  static QString formatPreviewString( const QVariant &value, bool htmlOutput = true );
611 
620  static QString createFieldEqualityExpression( const QString &fieldName, const QVariant &value );
621 
622 #ifdef SIP_RUN
623  SIP_PYOBJECT __repr__();
624  % MethodCode
625  QString str = QStringLiteral( "<QgsExpression: '%1'>" ).arg( sipCpp->expression() );
626  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
627  % End
628 #endif
629 
630  private:
631  void initGeomCalculator( const QgsExpressionContext *context );
632 
639  void detach() SIP_SKIP;
640 
641  QgsExpressionPrivate *d = nullptr;
642 
644  static void initFunctionHelp() SIP_SKIP;
646  static void initVariableHelp() SIP_SKIP;
647 
648  friend class QgsOgcUtils;
649 };
650 
652 
653 #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:122
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