QGIS API Documentation  3.9.0-Master (cebdc8dded)
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 
488  static QList<QgsExpressionFunction *> sFunctions SIP_SKIP;
489  static const QList<QgsExpressionFunction *> &Functions();
490 
492  static QStringList sBuiltinFunctions SIP_SKIP;
493  static const QStringList &BuiltinFunctions();
494 
502  static bool registerFunction( QgsExpressionFunction *function, bool transferOwnership = false );
503 
509  static bool unregisterFunction( const QString &name );
510 
515  static QList<QgsExpressionFunction *> sOwnedFunctions SIP_SKIP;
516 
521  static void cleanRegisteredFunctions();
522 
524  static bool isFunctionName( const QString &name );
525 
527  static int functionIndex( const QString &name );
528 
533  static int functionCount();
534 
540  static QString quotedColumnRef( QString name );
541 
547  static QString quotedString( QString text );
548 
557  static QString quotedValue( const QVariant &value );
558 
568  static QString quotedValue( const QVariant &value, QVariant::Type type );
569 
571 
578  static QString helpText( QString name );
579 
586  static QString variableHelpText( const QString &variableName );
587 
597  static QString formatVariableHelp( const QString &description, bool showValue = true, const QVariant &value = QVariant() );
598 
603  static QString group( const QString &group );
604 
613  static QString formatPreviewString( const QVariant &value, bool htmlOutput = true );
614 
623  static QString createFieldEqualityExpression( const QString &fieldName, const QVariant &value );
624 
625 #ifdef SIP_RUN
626  SIP_PYOBJECT __repr__();
627  % MethodCode
628  QString str = QStringLiteral( "<QgsExpression: '%1'>" ).arg( sipCpp->expression() );
629  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
630  % End
631 #endif
632 
633  private:
634  void initGeomCalculator( const QgsExpressionContext *context );
635 
636  struct HelpArg SIP_SKIP
637  {
638  HelpArg( const QString &arg, const QString &desc, bool descOnly = false, bool syntaxOnly = false,
639  bool optional = false, const QString &defaultVal = QString() )
640  : mArg( arg )
641  , mDescription( desc )
642  , mDescOnly( descOnly )
643  , mSyntaxOnly( syntaxOnly )
644  , mOptional( optional )
645  , mDefaultVal( defaultVal )
646  {}
647 
648  QString mArg;
649  QString mDescription;
650  bool mDescOnly;
651  bool mSyntaxOnly;
652  bool mOptional;
653  QString mDefaultVal;
654  };
655 
656  struct HelpExample SIP_SKIP
657  {
658  HelpExample( const QString &expression, const QString &returns, const QString &note = QString() )
659  : mExpression( expression )
660  , mReturns( returns )
661  , mNote( note )
662  {}
663 
664  QString mExpression;
665  QString mReturns;
666  QString mNote;
667  };
668 
669  struct HelpVariant SIP_SKIP
670  {
671  HelpVariant( const QString &name, const QString &description,
672  const QList<QgsExpression::HelpArg> &arguments = QList<QgsExpression::HelpArg>(),
673  bool variableLenArguments = false,
674  const QList<QgsExpression::HelpExample> &examples = QList<QgsExpression::HelpExample>(),
675  const QString &notes = QString() )
676  : mName( name )
677  , mDescription( description )
678  , mArguments( arguments )
679  , mVariableLenArguments( variableLenArguments )
680  , mExamples( examples )
681  , mNotes( notes )
682  {}
683 
684  QString mName;
685  QString mDescription;
686  QList<QgsExpression::HelpArg> mArguments;
687  bool mVariableLenArguments;
688  QList<QgsExpression::HelpExample> mExamples;
689  QString mNotes;
690  };
691 
692  struct Help SIP_SKIP
693  {
695  Help() = default;
696 
697  Help( const QString &name, const QString &type, const QString &description, const QList<QgsExpression::HelpVariant> &variants )
698  : mName( name )
699  , mType( type )
700  , mDescription( description )
701  , mVariants( variants )
702  {}
703 
704  QString mName;
705  QString mType;
706  QString mDescription;
707  QList<QgsExpression::HelpVariant> mVariants;
708  };
709 
716  void detach() SIP_SKIP;
717 
718  QgsExpressionPrivate *d = nullptr;
719 
720  static QHash<QString, Help> sFunctionHelpTexts;
721  static QHash<QString, QString> sVariableHelpTexts;
722  static QHash<QString, QString> sGroups;
723 
725  static void initFunctionHelp() SIP_SKIP;
727  static void initVariableHelp() SIP_SKIP;
728 
729  friend class QgsOgcUtils;
730 };
731 
733 
734 #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:42
A geometry is the spatial representation of a feature.
Definition: qgsgeometry.h:121
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:48
DistanceUnit
Units of distance.
Definition: qgsunittypes.h:66
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
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:49
AreaUnit
Units of area.
Definition: qgsunittypes.h:92