QGIS API Documentation  2.3.0-Master
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups Pages
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 <QMetaType>
20 #include <QStringList>
21 #include <QVariant>
22 #include <QList>
23 #include <QDomDocument>
24 
25 #include "qgsfield.h"
26 #include "qgsdistancearea.h"
27 
28 class QgsFeature;
29 class QgsGeometry;
30 class QgsOgcUtils;
31 class QgsVectorLayer;
33 
34 class QDomElement;
35 
89 class CORE_EXPORT QgsExpression
90 {
91  public:
92  QgsExpression( const QString& expr );
93  ~QgsExpression();
94 
96  bool hasParserError() const { return !mParserErrorString.isNull(); }
98  QString parserErrorString() const { return mParserErrorString; }
99 
100  class Node;
101 
103  const Node* rootNode() const { return mRootNode; }
104 
106  bool prepare( const QgsFields &fields );
107 
109  QStringList referencedColumns();
111  bool needsGeometry();
112 
113  // evaluation
114 
117  QVariant evaluate( const QgsFeature* f = NULL );
118 
122  inline QVariant evaluate( const QgsFeature& f ) { return evaluate( &f ); }
123 
126  QVariant evaluate( const QgsFeature* f, const QgsFields& fields );
127 
130  inline QVariant evaluate( const QgsFeature& f, const QgsFields& fields ) { return evaluate( &f, fields ); }
131 
133  bool hasEvalError() const { return !mEvalErrorString.isNull(); }
135  QString evalErrorString() const { return mEvalErrorString; }
137  void setEvalErrorString( QString str ) { mEvalErrorString = str; }
138 
140  void setCurrentRowNumber( int rowNumber ) { mRowNumber = rowNumber; }
142  int currentRowNumber() { return mRowNumber; }
143 
145  static void setSpecialColumn( const QString& name, QVariant value );
147  static void unsetSpecialColumn( const QString& name );
149  static QVariant specialColumn( const QString& name );
152  static bool hasSpecialColumn( const QString& name );
153 
154  void setScale( double scale ) { mScale = scale; }
155 
156  int scale() {return mScale; }
157 
159  const QString expression() const { return dump(); }
160 
162  QString dump() const;
163 
166  QgsDistanceArea *geomCalculator() { initGeomCalculator(); return mCalc; }
167 
169  // instead of the default.
170  void setGeomCalculator( const QgsDistanceArea &calc );
171 
179  static QString replaceExpressionText( const QString &action, const QgsFeature *feat,
180  QgsVectorLayer *layer,
181  const QMap<QString, QVariant> *substitutionMap = 0 );
183  {
186  };
188  {
189  // logical
192 
193  // comparison
194  boEQ, // =
195  boNE, // <>
196  boLE, // <=
197  boGE, // >=
198  boLT, // <
199  boGT, // >
207 
208  // math
215 
216  // strings
218  };
220  {
230  };
231 
232  static const char* BinaryOperatorText[];
233  static const char* UnaryOperatorText[];
234 
235  typedef QVariant( *FcnEval )( const QVariantList& values, const QgsFeature* f, QgsExpression* parent );
236 
237 
241  class CORE_EXPORT Function
242  {
243  public:
244  Function( QString fnname, int params, QString group, QString helpText = QString(), bool usesGeometry = false )
245  : mName( fnname ), mParams( params ), mUsesGeometry( usesGeometry ), mGroup( group ), mHelpText( helpText ) {}
247  QString name() { return mName; }
249  int params() { return mParams; }
251  bool usesgeometry() { return mUsesGeometry; }
253  QString group() { return mGroup; }
255  QString helptext() { return mHelpText.isEmpty() ? QgsExpression::helptext( mName ) : mHelpText; }
256 
257  virtual QVariant func( const QVariantList& values, const QgsFeature* f, QgsExpression* parent ) = 0;
258 
259  bool operator==( const Function& other ) const
260  {
261  if ( QString::compare( mName, other.mName, Qt::CaseInsensitive ) == 0 )
262  return true;
263 
264  return false;
265  }
266 
267  private:
268  QString mName;
269  int mParams;
271  QString mGroup;
272  QString mHelpText;
273  };
274 
275  class StaticFunction : public Function
276  {
277  public:
278  StaticFunction( QString fnname, int params, FcnEval fcn, QString group, QString helpText = QString(), bool usesGeometry = false )
279  : Function( fnname, params, group, helpText, usesGeometry ), mFnc( fcn ) {}
280 
281  virtual QVariant func( const QVariantList& values, const QgsFeature* f, QgsExpression* parent )
282  {
283  return mFnc( values, f, parent );
284  }
285 
286  private:
287  FcnEval mFnc;
288  };
289 
290  static const QList<Function*> &Functions();
291  static QList<Function*> gmFunctions;
292 
293  static QStringList gmBuiltinFunctions;
294  static const QStringList &BuiltinFunctions();
295 
296  static bool registerFunction( Function* function );
297  static bool unregisterFunction( QString name );
298 
299  // tells whether the identifier is a name of existing function
300  static bool isFunctionName( QString name );
301 
302  // return index of the function in Functions array
303  static int functionIndex( QString name );
304 
308  static int functionCount();
309 
313  static QList<Function*> specialColumns();
314 
316  static QString quotedColumnRef( QString name ) { return QString( "\"%1\"" ).arg( name.replace( "\"", "\"\"" ) ); }
318  static QString quotedString( QString text ) { return QString( "'%1'" ).arg( text.replace( "'", "''" ) ); }
319 
321 
322  class Visitor; // visitor interface is defined below
323 
324  enum NodeType
325  {
332  ntCondition
333  };
334 
335  class CORE_EXPORT Node
336  {
337  public:
338  virtual ~Node() {}
339  virtual NodeType nodeType() const = 0;
340  // abstract virtual eval function
341  // errors are reported to the parent
342  virtual QVariant eval( QgsExpression* parent, const QgsFeature* f ) = 0;
343 
344  // abstract virtual preparation function
345  // errors are reported to the parent
346  virtual bool prepare( QgsExpression* parent, const QgsFields &fields ) = 0;
347 
348  virtual QString dump() const = 0;
349 
350  virtual QStringList referencedColumns() const = 0;
351  virtual bool needsGeometry() const = 0;
352 
353  // support for visitor pattern
354  virtual void accept( Visitor& v ) const = 0;
355  };
356 
357  class CORE_EXPORT NodeList
358  {
359  public:
360  NodeList() {}
361  virtual ~NodeList() { qDeleteAll( mList ); }
362  void append( Node* node ) { mList.append( node ); }
363  int count() { return mList.count(); }
364  QList<Node*> list() { return mList; }
365 
366  virtual QString dump() const;
367 
368  protected:
369  QList<Node*> mList;
370  };
371 
372  class CORE_EXPORT Interval
373  {
374  // YEAR const value taken from postgres query
375  // SELECT EXTRACT(EPOCH FROM interval '1 year')
376  static const int YEARS = 31557600;
377  static const int MONTHS = 60 * 60 * 24 * 30;
378  static const int WEEKS = 60 * 60 * 24 * 7;
379  static const int DAY = 60 * 60 * 24;
380  static const int HOUR = 60 * 60;
381  static const int MINUTE = 60;
382  public:
383  Interval( double seconds = 0 ) : mSeconds( seconds ), mValid( true ) { }
384  ~Interval();
385  double years() { return mSeconds / YEARS;}
386  double months() { return mSeconds / MONTHS; }
387  double weeks() { return mSeconds / WEEKS;}
388  double days() { return mSeconds / DAY;}
389  double hours() { return mSeconds / HOUR;}
390  double minutes() { return mSeconds / MINUTE;}
391  double seconds() { return mSeconds; }
392  bool isValid() { return mValid; }
393  void setValid( bool valid ) { mValid = valid; }
394  bool operator==( const QgsExpression::Interval& other ) const;
395  static QgsExpression::Interval invalidInterVal();
396  static QgsExpression::Interval fromString( QString string );
397  private:
398  double mSeconds;
399  bool mValid;
400  };
401 
402  class CORE_EXPORT NodeUnaryOperator : public Node
403  {
404  public:
405  NodeUnaryOperator( UnaryOperator op, Node* operand ) : mOp( op ), mOperand( operand ) {}
406  ~NodeUnaryOperator() { delete mOperand; }
407 
408  UnaryOperator op() const { return mOp; }
409  Node* operand() const { return mOperand; }
410 
411  virtual NodeType nodeType() const { return ntUnaryOperator; }
412  virtual bool prepare( QgsExpression* parent, const QgsFields &fields );
413  virtual QVariant eval( QgsExpression* parent, const QgsFeature* f );
414  virtual QString dump() const;
415 
416  virtual QStringList referencedColumns() const { return mOperand->referencedColumns(); }
417  virtual bool needsGeometry() const { return mOperand->needsGeometry(); }
418  virtual void accept( Visitor& v ) const { v.visit( *this ); }
419 
420  protected:
423  };
424 
425  class CORE_EXPORT NodeBinaryOperator : public Node
426  {
427  public:
428  NodeBinaryOperator( BinaryOperator op, Node* opLeft, Node* opRight ) : mOp( op ), mOpLeft( opLeft ), mOpRight( opRight ) {}
429  ~NodeBinaryOperator() { delete mOpLeft; delete mOpRight; }
430 
431  BinaryOperator op() const { return mOp; }
432  Node* opLeft() const { return mOpLeft; }
433  Node* opRight() const { return mOpRight; }
434 
435  virtual NodeType nodeType() const { return ntBinaryOperator; }
436  virtual bool prepare( QgsExpression* parent, const QgsFields &fields );
437  virtual QVariant eval( QgsExpression* parent, const QgsFeature* f );
438  virtual QString dump() const;
439 
440  virtual QStringList referencedColumns() const { return mOpLeft->referencedColumns() + mOpRight->referencedColumns(); }
441  virtual bool needsGeometry() const { return mOpLeft->needsGeometry() || mOpRight->needsGeometry(); }
442  virtual void accept( Visitor& v ) const { v.visit( *this ); }
443 
444  int precedence() const;
445 
446  protected:
447  bool compare( double diff );
448  int computeInt( int x, int y );
449  double computeDouble( double x, double y );
450  QDateTime computeDateTimeFromInterval( QDateTime d, QgsExpression::Interval *i );
451 
455  };
456 
457  class CORE_EXPORT NodeInOperator : public Node
458  {
459  public:
460  NodeInOperator( Node* node, NodeList* list, bool notin = false ) : mNode( node ), mList( list ), mNotIn( notin ) {}
461  virtual ~NodeInOperator() { delete mNode; delete mList; }
462 
463  Node* node() const { return mNode; }
464  bool isNotIn() const { return mNotIn; }
465  NodeList* list() const { return mList; }
466 
467  virtual NodeType nodeType() const { return ntInOperator; }
468  virtual bool prepare( QgsExpression* parent, const QgsFields &fields );
469  virtual QVariant eval( QgsExpression* parent, const QgsFeature* f );
470  virtual QString dump() const;
471 
472  virtual QStringList referencedColumns() const { QStringList lst( mNode->referencedColumns() ); foreach ( Node* n, mList->list() ) lst.append( n->referencedColumns() ); return lst; }
473  virtual bool needsGeometry() const { bool needs = false; foreach ( Node* n, mList->list() ) needs |= n->needsGeometry(); return needs; }
474  virtual void accept( Visitor& v ) const { v.visit( *this ); }
475 
476  protected:
479  bool mNotIn;
480  };
481 
482  class CORE_EXPORT NodeFunction : public Node
483  {
484  public:
485  NodeFunction( int fnIndex, NodeList* args ) : mFnIndex( fnIndex ), mArgs( args ) {}
486  //NodeFunction( QString name, NodeList* args ) : mName(name), mArgs(args) {}
487  virtual ~NodeFunction() { delete mArgs; }
488 
489  int fnIndex() const { return mFnIndex; }
490  NodeList* args() const { return mArgs; }
491 
492  virtual NodeType nodeType() const { return ntFunction; }
493  virtual bool prepare( QgsExpression* parent, const QgsFields &fields );
494  virtual QVariant eval( QgsExpression* parent, const QgsFeature* f );
495  virtual QString dump() const;
496 
497  virtual QStringList referencedColumns() const { QStringList lst; if ( !mArgs ) return lst; foreach ( Node* n, mArgs->list() ) lst.append( n->referencedColumns() ); return lst; }
498  virtual bool needsGeometry() const { bool needs = Functions()[mFnIndex]->usesgeometry(); if ( mArgs ) { foreach ( Node* n, mArgs->list() ) needs |= n->needsGeometry(); } return needs; }
499  virtual void accept( Visitor& v ) const { v.visit( *this ); }
500 
501  protected:
502  //QString mName;
503  int mFnIndex;
505  };
506 
507  class CORE_EXPORT NodeLiteral : public Node
508  {
509  public:
510  NodeLiteral( QVariant value ) : mValue( value ) {}
511 
512  QVariant value() const { return mValue; }
513 
514  virtual NodeType nodeType() const { return ntLiteral; }
515  virtual bool prepare( QgsExpression* parent, const QgsFields &fields );
516  virtual QVariant eval( QgsExpression* parent, const QgsFeature* f );
517  virtual QString dump() const;
518 
519  virtual QStringList referencedColumns() const { return QStringList(); }
520  virtual bool needsGeometry() const { return false; }
521  virtual void accept( Visitor& v ) const { v.visit( *this ); }
522 
523  protected:
524  QVariant mValue;
525  };
526 
527  class CORE_EXPORT NodeColumnRef : public Node
528  {
529  public:
530  NodeColumnRef( QString name ) : mName( name ), mIndex( -1 ) {}
531 
532  QString name() const { return mName; }
533 
534  virtual NodeType nodeType() const { return ntColumnRef; }
535  virtual bool prepare( QgsExpression* parent, const QgsFields &fields );
536  virtual QVariant eval( QgsExpression* parent, const QgsFeature* f );
537  virtual QString dump() const;
538 
539  virtual QStringList referencedColumns() const { return QStringList( mName ); }
540  virtual bool needsGeometry() const { return false; }
541 
542  virtual void accept( Visitor& v ) const { v.visit( *this ); }
543 
544  protected:
545  QString mName;
546  int mIndex;
547  };
548 
549  class CORE_EXPORT WhenThen
550  {
551  public:
552  WhenThen( Node* whenExp, Node* thenExp ) : mWhenExp( whenExp ), mThenExp( thenExp ) {}
553  ~WhenThen() { delete mWhenExp; delete mThenExp; }
554 
555  //protected:
558  };
559  typedef QList<WhenThen*> WhenThenList;
560 
561  class CORE_EXPORT NodeCondition : public Node
562  {
563  public:
564  NodeCondition( WhenThenList* conditions, Node* elseExp = NULL ) : mConditions( *conditions ), mElseExp( elseExp ) { delete conditions; }
565  ~NodeCondition() { delete mElseExp; qDeleteAll( mConditions ); }
566 
567  virtual NodeType nodeType() const { return ntCondition; }
568  virtual QVariant eval( QgsExpression* parent, const QgsFeature* f );
569  virtual bool prepare( QgsExpression* parent, const QgsFields &fields );
570  virtual QString dump() const;
571 
572  virtual QStringList referencedColumns() const;
573  virtual bool needsGeometry() const;
574  virtual void accept( Visitor& v ) const { v.visit( *this ); }
575 
576  protected:
579  };
580 
582 
585  class CORE_EXPORT Visitor
586  {
587  public:
588  virtual ~Visitor() {}
589  virtual void visit( const NodeUnaryOperator& n ) = 0;
590  virtual void visit( const NodeBinaryOperator& n ) = 0;
591  virtual void visit( const NodeInOperator& n ) = 0;
592  virtual void visit( const NodeFunction& n ) = 0;
593  virtual void visit( const NodeLiteral& n ) = 0;
594  virtual void visit( const NodeColumnRef& n ) = 0;
595  virtual void visit( const NodeCondition& n ) = 0;
596  };
597 
599  void acceptVisitor( Visitor& v ) const;
600 
601  static QString helptext( QString name );
602  static QString group( QString group );
603 
604  protected:
605  // internally used to create an empty expression
606  QgsExpression() : mRootNode( 0 ), mRowNumber( 0 ), mCalc( 0 ) {}
607 
608  void initGeomCalculator();
609 
611 
614 
616  double mScale;
617  QString mExp;
618 
619  static QMap<QString, QVariant> gmSpecialColumns;
621 
622  friend class QgsOgcUtils;
623 
624  static void initFunctionHelp();
625  static QHash<QString, QString> gFunctionHelpTexts;
626  static QHash<QString, QString> gGroups;
627 };
628 
630 
631 #endif // QGSEXPRESSION_H
virtual void accept(Visitor &v) const
Class for parsing and evaluation of expressions (formerly called "search strings").
Definition: qgsexpression.h:89
virtual QStringList referencedColumns() const =0
bool hasEvalError() const
Returns true if an error occurred when evaluating last input.
QVariant evaluate(const QgsFeature &f, const QgsFields &fields)
Evaluate the feature and return the result.
bool hasParserError() const
Returns true if an error occurred when parsing the input expression.
Definition: qgsexpression.h:96
const QString expression() const
Return the expression string that was given when created.
virtual bool needsGeometry() const
Node is a class used by Line3D.
Definition: Node.h:23
virtual QVariant func(const QVariantList &values, const QgsFeature *f, QgsExpression *parent)
A abstract base class for defining QgsExpression functions.
bool operator==(const QgsFeatureIterator &fi1, const QgsFeatureIterator &fi2)
virtual bool needsGeometry() const
virtual QString dump() const =0
NodeCondition(WhenThenList *conditions, Node *elseExp=NULL)
static QString helptext(QString name)
virtual QStringList referencedColumns() const
virtual NodeType nodeType() const
static QString quotedColumnRef(QString name)
return quoted column reference (in double quotes)
Container of fields for a vector layer.
Definition: qgsfield.h:164
Interval(double seconds=0)
virtual NodeType nodeType() const
virtual bool prepare(QgsExpression *parent, const QgsFields &fields)=0
NodeList * list() const
virtual NodeType nodeType() const
The feature class encapsulates a single feature including its id, geometry and a list of field/values...
Definition: qgsfeature.h:114
QVariant value() const
int currentRowNumber()
Return the number used for $rownum special column.
QString mEvalErrorString
static QString quotedString(QString text)
return quoted string (in single quotes)
NodeBinaryOperator(BinaryOperator op, Node *opLeft, Node *opRight)
QString mParserErrorString
virtual QStringList referencedColumns() const
static const QList< Function * > & Functions()
virtual QStringList referencedColumns() const
Function(QString fnname, int params, QString group, QString helpText=QString(), bool usesGeometry=false)
static QHash< QString, QString > gFunctionHelpTexts
virtual NodeType nodeType() const
QgsDistanceArea * geomCalculator()
Return calculator used for distance and area calculations (used by internal functions) ...
NodeList * args() const
virtual QStringList referencedColumns() const
QgsDistanceArea * mCalc
virtual bool needsGeometry() const
QList< Node * > mList
virtual void accept(Visitor &v) const
static QHash< QString, QString > gGroups
const Node * rootNode() const
Returns root node of the expression. Root node is null is parsing has failed.
StaticFunction(QString fnname, int params, FcnEval fcn, QString group, QString helpText=QString(), bool usesGeometry=false)
NodeInOperator(Node *node, NodeList *list, bool notin=false)
QString helptext()
The help text for the function.
static QList< Function * > gmFunctions
QString name()
The name of the function.
void setCurrentRowNumber(int rowNumber)
Set the number for $rownum special column.
WhenThen(Node *whenExp, Node *thenExp)
NodeLiteral(QVariant value)
virtual NodeType nodeType() const
NodeUnaryOperator(UnaryOperator op, Node *operand)
BinaryOperator op() const
virtual void accept(Visitor &v) const
virtual QVariant eval(QgsExpression *parent, const QgsFeature *f)=0
void setEvalErrorString(QString str)
Set evaluation error (used internally by evaluation functions)
NodeFunction(int fnIndex, NodeList *args)
General purpose distance and area calculator.
virtual void accept(Visitor &v) const
virtual void accept(Visitor &v) const
QString group()
The group the function belongs to.
QList< WhenThen * > WhenThenList
virtual NodeType nodeType() const
virtual void accept(Visitor &v) const
virtual void visit(const NodeUnaryOperator &n)=0
QVariant evaluate(const QgsFeature &f)
Evaluate the feature and return the result.
int params()
The number of parameters this function takes.
virtual QStringList referencedColumns() const
virtual void accept(Visitor &v) const
support for visitor pattern - algorithms dealing with the expressions may be implemented without modi...
virtual bool needsGeometry() const
virtual bool needsGeometry() const =0
bool operator==(const Function &other) const
static QStringList gmBuiltinFunctions
void append(Node *node)
UnaryOperator op() const
void setValid(bool valid)
virtual QStringList referencedColumns() const
This is the base class for vector data providers.
void setScale(double scale)
Represents a vector layer which manages a vector based data sets.
QString parserErrorString() const
Returns parser error.
Definition: qgsexpression.h:98
Q_DECLARE_METATYPE(QgsExpression::Interval)
The QgsOgcUtils class provides various utility functions for conversion between OGC (Open Geospatial ...
Definition: qgsogcutils.h:30
QString evalErrorString() const
Returns evaluation error.
virtual bool needsGeometry() const
virtual bool needsGeometry() const
bool usesgeometry()
Does this function use a geometry object.
virtual NodeType nodeType() const
QList< Node * > list()
static QMap< QString, QVariant > gmSpecialColumns