QGIS API Documentation  3.4.15-Madeira (e83d02e274)
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 
232  const QgsExpressionNode *rootNode() const;
233 
239  bool prepare( const QgsExpressionContext *context );
240 
250  QSet<QString> referencedColumns() const;
251 
259  QSet<QString> referencedVariables() const;
260 
266  QSet<QString> referencedFunctions() const;
267 
268 #ifndef SIP_RUN
269 
276  QList<const QgsExpressionNode *> nodes( ) const;
277 
284  template <class T>
285  QList<const T *> findNodes( ) const
286  {
287  QList<const T *> lst;
288  const QList<const QgsExpressionNode *> allNodes( nodes() );
289  for ( const auto &node : allNodes )
290  {
291  const T *n = dynamic_cast<const T *>( node );
292  if ( n )
293  lst << n;
294  }
295  return lst;
296  }
297 #endif
298 
304  QSet<int> referencedAttributeIndexes( const QgsFields &fields ) const;
305 
307  bool needsGeometry() const;
308 
309  // evaluation
310 
316  QVariant evaluate();
317 
324  QVariant evaluate( const QgsExpressionContext *context );
325 
327  bool hasEvalError() const;
329  QString evalErrorString() const;
331  void setEvalErrorString( const QString &str );
332 
337  bool isField() const;
338 
347  static bool checkExpression( const QString &text, const QgsExpressionContext *context, QString &errorMessage SIP_OUT );
348 
354  void setExpression( const QString &expression );
355 
361  QString expression() const;
362 
369  QString dump() const;
370 
378  QgsDistanceArea *geomCalculator();
379 
393  void setGeomCalculator( const QgsDistanceArea *calc );
394 
402  QgsUnitTypes::DistanceUnit distanceUnits() const;
403 
413  void setDistanceUnits( QgsUnitTypes::DistanceUnit unit );
414 
422  QgsUnitTypes::AreaUnit areaUnits() const;
423 
433  void setAreaUnits( QgsUnitTypes::AreaUnit unit );
434 
446  static QString replaceExpressionText( const QString &action, const QgsExpressionContext *context,
447  const QgsDistanceArea *distanceArea = nullptr );
448 
456  static QSet<QString> referencedVariables( const QString &text );
457 
468  static double evaluateToDouble( const QString &text, double fallbackValue );
469 
471  {
481  };
482 
484  static QList<QgsExpressionFunction *> sFunctions SIP_SKIP;
485  static const QList<QgsExpressionFunction *> &Functions();
486 
488  static QStringList sBuiltinFunctions SIP_SKIP;
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 QList<QgsExpressionFunction *> sOwnedFunctions SIP_SKIP;
512 
517  static void cleanRegisteredFunctions();
518 
520  static bool isFunctionName( const QString &name );
521 
523  static int functionIndex( const QString &name );
524 
529  static int functionCount();
530 
536  static QString quotedColumnRef( QString name );
537 
543  static QString quotedString( QString text );
544 
553  static QString quotedValue( const QVariant &value );
554 
564  static QString quotedValue( const QVariant &value, QVariant::Type type );
565 
567 
574  static QString helpText( QString name );
575 
582  static QString variableHelpText( const QString &variableName );
583 
593  static QString formatVariableHelp( const QString &description, bool showValue = true, const QVariant &value = QVariant() );
594 
599  static QString group( const QString &group );
600 
609  static QString formatPreviewString( const QVariant &value, bool htmlOutput = true );
610 
619  static QString createFieldEqualityExpression( const QString &fieldName, const QVariant &value );
620 
621 #ifdef SIP_RUN
622  SIP_PYOBJECT __repr__();
623  % MethodCode
624  QString str = QStringLiteral( "<QgsExpression: '%1'>" ).arg( sipCpp->expression() );
625  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
626  % End
627 #endif
628 
629  private:
630  void initGeomCalculator( const QgsExpressionContext *context );
631 
632  struct HelpArg SIP_SKIP
633  {
634  HelpArg( const QString &arg, const QString &desc, bool descOnly = false, bool syntaxOnly = false,
635  bool optional = false, const QString &defaultVal = QString() )
636  : mArg( arg )
637  , mDescription( desc )
638  , mDescOnly( descOnly )
639  , mSyntaxOnly( syntaxOnly )
640  , mOptional( optional )
641  , mDefaultVal( defaultVal )
642  {}
643 
644  QString mArg;
645  QString mDescription;
646  bool mDescOnly;
647  bool mSyntaxOnly;
648  bool mOptional;
649  QString mDefaultVal;
650  };
651 
652  struct HelpExample SIP_SKIP
653  {
654  HelpExample( const QString &expression, const QString &returns, const QString &note = QString() )
655  : mExpression( expression )
656  , mReturns( returns )
657  , mNote( note )
658  {}
659 
660  QString mExpression;
661  QString mReturns;
662  QString mNote;
663  };
664 
665  struct HelpVariant SIP_SKIP
666  {
667  HelpVariant( const QString &name, const QString &description,
668  const QList<QgsExpression::HelpArg> &arguments = QList<QgsExpression::HelpArg>(),
669  bool variableLenArguments = false,
670  const QList<QgsExpression::HelpExample> &examples = QList<QgsExpression::HelpExample>(),
671  const QString &notes = QString() )
672  : mName( name )
673  , mDescription( description )
674  , mArguments( arguments )
675  , mVariableLenArguments( variableLenArguments )
676  , mExamples( examples )
677  , mNotes( notes )
678  {}
679 
680  QString mName;
681  QString mDescription;
682  QList<QgsExpression::HelpArg> mArguments;
683  bool mVariableLenArguments;
684  QList<QgsExpression::HelpExample> mExamples;
685  QString mNotes;
686  };
687 
688  struct Help SIP_SKIP
689  {
691  Help() = default;
692 
693  Help( const QString &name, const QString &type, const QString &description, const QList<QgsExpression::HelpVariant> &variants )
694  : mName( name )
695  , mType( type )
696  , mDescription( description )
697  , mVariants( variants )
698  {}
699 
700  QString mName;
701  QString mType;
702  QString mDescription;
703  QList<QgsExpression::HelpVariant> mVariants;
704  };
705 
712  void detach() SIP_SKIP;
713 
714  QgsExpressionPrivate *d = nullptr;
715 
716  static QHash<QString, Help> sFunctionHelpTexts;
717  static QHash<QString, QString> sVariableHelpTexts;
718  static QHash<QString, QString> sGroups;
719 
721  static void initFunctionHelp() SIP_SKIP;
723  static void initVariableHelp() SIP_SKIP;
724 
725  friend class QgsOgcUtils;
726 };
727 
729 
730 #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:106
The feature class encapsulates a single feature including its id, geometry and a list of field/values...
Definition: qgsfeature.h:55
Q_DECLARE_METATYPE(QModelIndex)
#define SIP_SKIP
Definition: qgis_sip.h:119
Expression contexts are used to encapsulate the parameters around which a QgsExpression should be eva...
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:53
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:51
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:79