QGIS/python/core/qgsfeaturerequest.sip

class QgsFeatureRequest
{
%TypeHeaderCode
#include <qgsfeaturerequest.h>
%End

  public:
    enum Flag
    {
      NoFlags,
      NoGeometry,          //!< Geometry is not required. It may still be returned if e.g. required for a filter condition.
      SubsetOfAttributes,  //!< Fetch only a subset of attributes (setSubsetOfAttributes sets this flag)
      ExactIntersect       //!< Use exact geometry intersection (slower) instead of bounding boxes
    };
    typedef QFlags<QgsFeatureRequest::Flag> Flags;

    /**
     * Types of filters.
     */
    enum FilterType
    {
      FilterNone,       //!< No filter is applied
      FilterFid,        //!< Filter using feature ID
      FilterExpression, //!< Filter using expression
      FilterFids        //!< Filter using feature IDs
    };

    //! Handling of features with invalid geometries
    enum InvalidGeometryCheck
    {
      GeometryNoCheck,
      GeometrySkipInvalid,
      GeometryAbortOnInvalid,
    };

    /**
     * The OrderByClause class represents an order by clause for a QgsFeatureRequest.
     *
     * It can be a simple field or an expression. Multiple order by clauses can be added to
     * a QgsFeatureRequest to fine tune the behavior if a single field or expression is not
     * enough to completely specify the required behavior.
     *
     * If expression compilation is activated in the settings and the expression can be
     * translated for the provider in question, it will be evaluated on provider side.
     * If one of these two premises does not apply, the ordering will take place locally
     * which results in increased memory and CPU usage.
     *
     * If the ordering is done on strings, the order depends on the system's locale if the
     * local fallback implementation is used. The order depends on the server system's locale
     * and implementation if ordering is done on the server.
     *
     * In case the fallback code needs to be used, a limit set on the request will be respected
     * for the features returned by the iterator but internally all features will be requested
     * from the provider.
     *
     * @note added in QGIS 2.14
     */
    class OrderByClause
    {
      public:
        /**
         * Creates a new OrderByClause for a QgsFeatureRequest
         *
         * @param expression The expression to use for ordering
         * @param ascending  If the order should be ascending (1,2,3) or descending (3,2,1)
         *                   If the order is ascending, by default nulls are last
         *                   If the order is descending, by default nulls are first
         */
        OrderByClause( const QString &expression, bool ascending = true );
        /**
         * Creates a new OrderByClause for a QgsFeatureRequest
         *
         * @param expression The expression to use for ordering
         * @param ascending  If the order should be ascending (1,2,3) or descending (3,2,1)
         * @param nullsfirst If true, NULLS are at the beginning, if false, NULLS are at the end
         */
        OrderByClause( const QString &expression, bool ascending, bool nullsfirst );

        /**
         * The expression
         * @return the expression
         */
        QgsExpression expression() const;

        /**
         * Prepare the expression with the given context.
         *
         * \see QgsExpression::prepare
         *
         * \since QGIS 3.0
         */
        bool prepare( QgsExpressionContext *context );

        /**
         * Order ascending
         * @return If ascending order is requested
         */
        bool ascending() const;

        /**
         * Set if ascending order is requested
         */
        void setAscending( bool ascending );

        /**
         * Set if NULLS should be returned first
         * @return if NULLS should be returned first
         */
        bool nullsFirst() const;

        /**
         * Set if NULLS should be returned first
         */
        void setNullsFirst( bool nullsFirst );

        /**
         * Dumps the content to an SQL equivalent
         */
        QString dump() const;
    };

    /**
     * Represents a list of OrderByClauses, with the most important first and the least
     * important last.
     *
     * @note added in QGIS 2.14
     */
    class OrderBy
    {
      public:
        /**
         * Create a new empty order by
         */
        OrderBy();

        /**
         * Create a new order by from a list of clauses
         */
        OrderBy( const QList<QgsFeatureRequest::OrderByClause> &other );

        /**
         * Get a copy as a list of OrderByClauses
         *
         * This is only required in python where the inheritance
         * is not properly propagated and this makes it usable.
         */
        QList<QgsFeatureRequest::OrderByClause> list() const;

        /**
         * Serialize to XML
         */
        void save( QDomElement &elem ) const;

        /**
         * Deserialize from XML
         */
        void load( const QDomElement &elem );

        /**
         * Returns a set of used attributes
         */
        QSet<QString> usedAttributes() const;

        /**
         * Dumps the content to an SQL equivalent syntax
         */
        QString dump() const;
    };

    /**
     * A special attribute that if set matches all attributes
     */
    static const QString ALL_ATTRIBUTES;

    //! construct a default request: for all features get attributes and geometries
    QgsFeatureRequest();
    //! construct a request with feature ID filter
    explicit QgsFeatureRequest( QgsFeatureId fid );
    //! construct a request with rectangle filter
    explicit QgsFeatureRequest( const QgsRectangle &rect );
    //! construct a request with a filter expression
    explicit QgsFeatureRequest( const QgsExpression &expr, const QgsExpressionContext &context = QgsExpressionContext() );
    //! copy constructor
    QgsFeatureRequest( const QgsFeatureRequest &rh );

    ~QgsFeatureRequest();

    /**
     * Return the filter type which is currently set on this request
     *
     * @return Filter type
     */
    FilterType filterType() const;

    /**
     * Set rectangle from which features will be taken. Empty rectangle removes the filter.
     */
    QgsFeatureRequest &setFilterRect( const QgsRectangle &rect );

    /**
     * Get the rectangle from which features will be taken.
     */
    const QgsRectangle &filterRect() const;

    //! Set feature ID that should be fetched.
    QgsFeatureRequest &setFilterFid( qint64 fid );
    //! Get the feature ID that should be fetched.
    qint64 filterFid() const;

    //! Set feature IDs that should be fetched.
    QgsFeatureRequest &setFilterFids( const QgsFeatureIds &fids );
    //! Get feature IDs that should be fetched.
    const QgsFeatureIds &filterFids() const;

    /**
     * Sets invalid geometry checking behavior.
     * \note Invalid geometry checking is not performed when retrieving features
     * directly from a QgsVectorDataProvider.
     * \see invalidGeometryCheck()
     * \since QGIS 3.0
     */
    QgsFeatureRequest &setInvalidGeometryCheck( InvalidGeometryCheck check );

    /**
     * Returns the invalid geometry checking behavior.
     * \see setInvalidGeometryCheck()
     * \since QGIS 3.0
     */
    InvalidGeometryCheck invalidGeometryCheck() const;

    /**
     * Sets a callback function to use when encountering an invalid geometry and
     * invalidGeometryCheck() is set to GeometryAbortOnInvalid. This function will be
     * called using the feature with invalid geometry as a parameter.
     * \since QGIS 3.0
     * \see invalidGeometryCallback()
     */
    QgsFeatureRequest &setInvalidGeometryCallback( SIP_PYCALLABLE /AllowNone/ );
%MethodCode
        Py_BEGIN_ALLOW_THREADS

        sipCpp->setInvalidGeometryCallback([a0](const QgsFeature &arg) {
            SIP_BLOCK_THREADS
            Py_XDECREF( sipCallMethod(NULL, a0, "D", &arg, sipType_QgsFeature, NULL) );
            SIP_UNBLOCK_THREADS
        });

        sipRes = sipCpp;

        Py_END_ALLOW_THREADS
%End

    /**
     * Returns the callback function to use when encountering an invalid geometry and
     * invalidGeometryCheck() is set to GeometryAbortOnInvalid.
     * \since QGIS 3.0
     * \note not available in Python bindings
     * \see setInvalidGeometryCallback()
     */
    // std::function< void( const QgsFeature & ) > invalidGeometryCallback() const;

    /** Set the filter expression. {@see QgsExpression}
     * @param expression expression string
     * @see filterExpression
     * @see setExpressionContext
     */
    QgsFeatureRequest &setFilterExpression( const QString &expression );

    /** Returns the filter expression if set.
     * @see setFilterExpression
     * @see expressionContext
     */
    QgsExpression *filterExpression() const;

    /** Modifies the existing filter expression to add an additional expression filter. The
     * filter expressions are combined using AND, so only features matching both
     * the existing expression and the additional expression will be returned.
     * @note added in QGIS 2.14
     */
    QgsFeatureRequest &combineFilterExpression( const QString &expression );

    /** Returns the expression context used to evaluate filter expressions.
     * @note added in QGIS 2.12
     * @see setExpressionContext
     * @see filterExpression
     */
    QgsExpressionContext *expressionContext();

    /** Sets the expression context used to evaluate filter expressions.
     * @note added in QGIS 2.12
     * @see expressionContext
     * @see setFilterExpression
     */
    QgsFeatureRequest &setExpressionContext( const QgsExpressionContext &context );

    /**
     * Disables filter conditions.
     * The spatial filter (filterRect) will be kept in place.
     *
     * @return The object the method is called on for chaining
     *
     * @note Added in 2.12
     */
    QgsFeatureRequest &disableFilter();

    /**
     * Adds a new OrderByClause, appending it as the least important one.
     *
     * @param expression The expression to use for ordering
     * @param ascending  If the order should be ascending (1,2,3) or descending (3,2,1)
     *                   If the order is ascending, by default nulls are last
     *                   If the order is descending, by default nulls are first
     *
     * @note added in QGIS 2.14
     */

    QgsFeatureRequest &addOrderBy( const QString &expression, bool ascending = true );
    /**
     * Adds a new OrderByClause, appending it as the least important one.
     *
     * @param expression The expression to use for ordering
     * @param ascending  If the order should be ascending (1,2,3) or descending (3,2,1)
     * @param nullsfirst If true, NULLS are at the beginning, if false, NULLS are at the end
     *
     * @note added in QGIS 2.14
     */
    QgsFeatureRequest &addOrderBy( const QString &expression, bool ascending, bool nullsfirst );

    /**
     * Return a list of order by clauses specified for this feature request.
     *
     * @note added in 2.14
     */
    QgsFeatureRequest::OrderBy orderBy() const;

    /**
     * Set a list of order by clauses.
     *
     * @note added in 2.14
     */
    QgsFeatureRequest &setOrderBy( const QgsFeatureRequest::OrderBy &orderBy );

    /** Set the maximum number of features to request.
     * @param limit maximum number of features, or -1 to request all features.
     * @see limit()
     * @note added in QGIS 2.14
     */
    QgsFeatureRequest &setLimit( long limit );

    /** Returns the maximum number of features to request, or -1 if no limit set.
     * @see setLimit
     * @note added in QGIS 2.14
     */
    long limit() const;

    //! Set flags that affect how features will be fetched
    QgsFeatureRequest &setFlags( const Flags &flags );
    const Flags &flags() const;

    //! Set a subset of attributes that will be fetched. Empty list means that all attributes are used.
    //! To disable fetching attributes, reset the FetchAttributes flag (which is set by default)
    QgsFeatureRequest &setSubsetOfAttributes( const QgsAttributeList &attrs );
    /**
     * Return the subset of attributes which at least need to be fetched
     * @return A list of attributes to be fetched
     */
    QgsAttributeList subsetOfAttributes() const;

    //! Set a subset of attributes by names that will be fetched
    QgsFeatureRequest &setSubsetOfAttributes( const QStringList &attrNames, const QgsFields &fields );

    //! Set a simplification method for geometries that will be fetched
    //! @note added in 2.2
    QgsFeatureRequest &setSimplifyMethod( const QgsSimplifyMethod &simplifyMethod );
    //! Get simplification method for geometries that will be fetched
    //! @note added in 2.2
    const QgsSimplifyMethod &simplifyMethod() const;

    /**
     * Check if a feature is accepted by this requests filter
     *
     * @param feature  The feature which will be tested
     *
     * @return true, if the filter accepts the feature
     *
     * @note added in 2.1
     */
    bool acceptFeature( const QgsFeature &feature );

};


/** Base class that can be used for any class that is capable of returning features
 * @note added in 2.4
 */
class QgsAbstractFeatureSource
{
%TypeHeaderCode
#include <qgsfeaturerequest.h>
%End
  public:
    virtual ~QgsAbstractFeatureSource();

    /**
     * Get an iterator for features matching the specified request
     * @param request The request
     * @return A feature iterator
     */
    virtual QgsFeatureIterator getFeatures( const QgsFeatureRequest &request = QgsFeatureRequest() ) = 0;

  protected:
    void iteratorOpened( QgsAbstractFeatureIterator *it );
    void iteratorClosed( QgsAbstractFeatureIterator *it );
};