QGIS API Documentation  3.3.0-Master (77eafc0)
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 
389  void setGeomCalculator( const QgsDistanceArea *calc );
390 
398  QgsUnitTypes::DistanceUnit distanceUnits() const;
399 
407  void setDistanceUnits( QgsUnitTypes::DistanceUnit unit );
408 
416  QgsUnitTypes::AreaUnit areaUnits() const;
417 
425  void setAreaUnits( QgsUnitTypes::AreaUnit unit );
426 
438  static QString replaceExpressionText( const QString &action, const QgsExpressionContext *context,
439  const QgsDistanceArea *distanceArea = nullptr );
440 
448  static QSet<QString> referencedVariables( const QString &text );
449 
460  static double evaluateToDouble( const QString &text, double fallbackValue );
461 
463  {
473  };
474 
476  static QList<QgsExpressionFunction *> sFunctions SIP_SKIP;
477  static const QList<QgsExpressionFunction *> &Functions();
478 
480  static QStringList sBuiltinFunctions SIP_SKIP;
481  static const QStringList &BuiltinFunctions();
482 
490  static bool registerFunction( QgsExpressionFunction *function, bool transferOwnership = false );
491 
497  static bool unregisterFunction( const QString &name );
498 
503  static QList<QgsExpressionFunction *> sOwnedFunctions SIP_SKIP;
504 
509  static void cleanRegisteredFunctions();
510 
512  static bool isFunctionName( const QString &name );
513 
515  static int functionIndex( const QString &name );
516 
521  static int functionCount();
522 
528  static QString quotedColumnRef( QString name );
529 
535  static QString quotedString( QString text );
536 
545  static QString quotedValue( const QVariant &value );
546 
556  static QString quotedValue( const QVariant &value, QVariant::Type type );
557 
559 
566  static QString helpText( 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 
600  static QString formatPreviewString( const QVariant &value );
601 
610  static QString createFieldEqualityExpression( const QString &fieldName, const QVariant &value );
611 
612  private:
613  void initGeomCalculator();
614 
615  struct HelpArg SIP_SKIP
616  {
617  HelpArg( const QString &arg, const QString &desc, bool descOnly = false, bool syntaxOnly = false,
618  bool optional = false, const QString &defaultVal = QString() )
619  : mArg( arg )
620  , mDescription( desc )
621  , mDescOnly( descOnly )
622  , mSyntaxOnly( syntaxOnly )
623  , mOptional( optional )
624  , mDefaultVal( defaultVal )
625  {}
626 
627  QString mArg;
628  QString mDescription;
629  bool mDescOnly;
630  bool mSyntaxOnly;
631  bool mOptional;
632  QString mDefaultVal;
633  };
634 
635  struct HelpExample SIP_SKIP
636  {
637  HelpExample( const QString &expression, const QString &returns, const QString &note = QString() )
638  : mExpression( expression )
639  , mReturns( returns )
640  , mNote( note )
641  {}
642 
643  QString mExpression;
644  QString mReturns;
645  QString mNote;
646  };
647 
648  struct HelpVariant SIP_SKIP
649  {
650  HelpVariant( const QString &name, const QString &description,
651  const QList<QgsExpression::HelpArg> &arguments = QList<QgsExpression::HelpArg>(),
652  bool variableLenArguments = false,
653  const QList<QgsExpression::HelpExample> &examples = QList<QgsExpression::HelpExample>(),
654  const QString &notes = QString() )
655  : mName( name )
656  , mDescription( description )
657  , mArguments( arguments )
658  , mVariableLenArguments( variableLenArguments )
659  , mExamples( examples )
660  , mNotes( notes )
661  {}
662 
663  QString mName;
664  QString mDescription;
665  QList<QgsExpression::HelpArg> mArguments;
666  bool mVariableLenArguments;
667  QList<QgsExpression::HelpExample> mExamples;
668  QString mNotes;
669  };
670 
671  struct Help SIP_SKIP
672  {
674  Help() = default;
675 
676  Help( const QString &name, const QString &type, const QString &description, const QList<QgsExpression::HelpVariant> &variants )
677  : mName( name )
678  , mType( type )
679  , mDescription( description )
680  , mVariants( variants )
681  {}
682 
683  QString mName;
684  QString mType;
685  QString mDescription;
686  QList<QgsExpression::HelpVariant> mVariants;
687  };
688 
695  void detach() SIP_SKIP;
696 
697  QgsExpressionPrivate *d = nullptr;
698 
699  static QHash<QString, Help> sFunctionHelpTexts;
700  static QHash<QString, QString> sVariableHelpTexts;
701  static QHash<QString, QString> sGroups;
702 
704  static void initFunctionHelp() SIP_SKIP;
706  static void initVariableHelp() SIP_SKIP;
707 
708  friend class QgsOgcUtils;
709 };
710 
712 
713 #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:104
The feature class encapsulates a single feature including its id, geometry and a list of field/values...
Definition: qgsfeature.h:62
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