qgsexpression.h

Go to the documentation of this file.

/***************************************************************************
                               qgsexpression.h
                             -------------------
    begin                : August 2011
    copyright            : (C) 2011 Martin Dobias
    email                : wonder.sk at gmail dot com
 ***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 ***************************************************************************/
 
#ifndef QGSEXPRESSION_H
#define QGSEXPRESSION_H
 
#include "qgis_core.h"
#include <QMetaType>
#include <QStringList>
#include <QVariant>
#include <QList>
#include <QDomDocument>
#include <QCoreApplication>
#include <QSet>
#include <functional>
 
#include "qgis.h"
#include "qgsunittypes.h"
#include "qgsinterval.h"
#include "qgsexpressionnode.h"
 
class QgsFeature;
class QgsGeometry;
class QgsOgcUtils;
class QgsVectorLayer;
class QgsVectorDataProvider;
class QgsField;
class QgsFields;
class QgsDistanceArea;
class QDomElement;
class QgsExpressionContext;
class QgsExpressionPrivate;
class QgsExpressionFunction;
 
class CORE_EXPORT QgsExpression
{
    Q_DECLARE_TR_FUNCTIONS( QgsExpression )
  public:
 
    struct CORE_EXPORT ParserError
    {
      enum ParserErrorType
      {
        Unknown = 0,  
        FunctionUnknown = 1, 
        FunctionWrongArgs = 2, 
        FunctionInvalidParams = 3, 
        FunctionNamedArgsError = 4 
      };
 
      ParserErrorType errorType = ParserErrorType::Unknown;
 
      QString errorMsg;
 
      int firstLine = 0;
 
      int firstColumn = 0;
 
      int lastLine = 0;
 
      int lastColumn = 0;
    };
 
    QgsExpression( const QString &expr );
 
    QgsExpression( const QgsExpression &other );
 
    QgsExpression &operator=( const QgsExpression &other );
 
    operator QString() const SIP_SKIP;
 
    QgsExpression();
 
    ~QgsExpression();
 
    bool operator==( const QgsExpression &other ) const;
 
    bool isValid() const;
 
    bool hasParserError() const;
    QString parserErrorString() const;
 
    QList<QgsExpression::ParserError> parserErrors() const;
 
    const QgsExpressionNode *rootNode() const;
 
    bool prepare( const QgsExpressionContext *context );
 
    QSet<QString> referencedColumns() const;
 
    QSet<QString> referencedVariables() const;
 
    QSet<QString> referencedFunctions() const;
 
#ifndef SIP_RUN
 
    QList<const QgsExpressionNode *> nodes( ) const;
 
    template <class T>
    QList<const T *> findNodes( ) const
    {
      QList<const T *> lst;
      const QList<const QgsExpressionNode *> allNodes( nodes() );
      for ( const auto &node : allNodes )
      {
        const T *n = dynamic_cast<const T *>( node );
        if ( n )
          lst << n;
      }
      return lst;
    }
#endif
 
    QSet<int> referencedAttributeIndexes( const QgsFields &fields ) const;
 
    bool needsGeometry() const;
 
    // evaluation
 
    QVariant evaluate();
 
    QVariant evaluate( const QgsExpressionContext *context );
 
    bool hasEvalError() const;
    QString evalErrorString() const;
    void setEvalErrorString( const QString &str );
 
    bool isField() const;
 
    static int expressionToLayerFieldIndex( const QString &expression, const QgsVectorLayer *layer );
 
    static QString quoteFieldExpression( const QString &expression, const QgsVectorLayer *layer );
 
    static bool checkExpression( const QString &text, const QgsExpressionContext *context, QString &errorMessage SIP_OUT );
 
    void setExpression( const QString &expression );
 
    QString expression() const;
 
    QString dump() const;
 
    QgsDistanceArea *geomCalculator();
 
    void setGeomCalculator( const QgsDistanceArea *calc );
 
    QgsUnitTypes::DistanceUnit distanceUnits() const;
 
    void setDistanceUnits( QgsUnitTypes::DistanceUnit unit );
 
    QgsUnitTypes::AreaUnit areaUnits() const;
 
    void setAreaUnits( QgsUnitTypes::AreaUnit unit );
 
    static QString replaceExpressionText( const QString &action, const QgsExpressionContext *context,
                                          const QgsDistanceArea *distanceArea = nullptr );
 
    static QSet<QString> referencedVariables( const QString &text );
 
    static double evaluateToDouble( const QString &text, double fallbackValue );
 
    enum SpatialOperator
    {
      soBbox,
      soIntersects,
      soContains,
      soCrosses,
      soEquals,
      soDisjoint,
      soOverlaps,
      soTouches,
      soWithin,
    };
 
    static const QList<QgsExpressionFunction *> &Functions();
 
    static const QStringList &BuiltinFunctions();
 
    static bool registerFunction( QgsExpressionFunction *function, bool transferOwnership = false );
 
    static bool unregisterFunction( const QString &name );
 
    static void cleanRegisteredFunctions();
 
    static bool isFunctionName( const QString &name );
 
    static int functionIndex( const QString &name );
 
    static int functionCount();
 
    static QString quotedColumnRef( QString name );
 
    static QString quotedString( QString text );
 
    static QString quotedValue( const QVariant &value );
 
    static QString quotedValue( const QVariant &value, QVariant::Type type );
 
 
    static QString helpText( QString name );
 
    static QStringList tags( const QString &name );
 
    static bool addVariableHelpText( const QString name, const QString &description );
 
    static QString variableHelpText( const QString &variableName );
 
    static QString formatVariableHelp( const QString &description, bool showValue = true, const QVariant &value = QVariant() );
 
    static QString group( const QString &group );
 
    static QString formatPreviewString( const QVariant &value, bool htmlOutput = true, int maximumPreviewLength = 60 );
 
    static QString createFieldEqualityExpression( const QString &fieldName, const QVariant &value, QVariant::Type fieldType = QVariant::Type::Invalid );
 
    static bool isFieldEqualityExpression( const QString &expression, QString &field SIP_OUT, QVariant &value SIP_OUT );
 
    static bool attemptReduceToInClause( const QStringList &expressions, QString &result SIP_OUT );
 
#ifdef SIP_RUN
    SIP_PYOBJECT __repr__();
    % MethodCode
    QString str = QStringLiteral( "<QgsExpression: '%1'>" ).arg( sipCpp->expression() );
    sipRes = PyUnicode_FromString( str.toUtf8().constData() );
    % End
#endif
 
  private:
    void initGeomCalculator( const QgsExpressionContext *context );
 
    void detach() SIP_SKIP;
 
    QgsExpressionPrivate *d = nullptr;
 
    static void initFunctionHelp() SIP_SKIP;
    static void initVariableHelp() SIP_SKIP;
 
    friend class QgsOgcUtils;
};
 
Q_DECLARE_METATYPE( QgsExpression )
 
#endif // QGSEXPRESSION_H