QGIS API Documentation  3.0.2-Girona (307d082)
Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | Friends | List of all members
QgsAbstractFeatureIterator Class Referenceabstract

Internal feature iterator to be implemented within data providers. More...

#include <qgsfeatureiterator.h>

Inheritance diagram for QgsAbstractFeatureIterator:
Inheritance graph
[legend]

Public Types

enum  CompileStatus { NoCompilation, PartiallyCompiled, Compiled }
 Status of expression compilation for filter expression requests. More...
 

Public Member Functions

 QgsAbstractFeatureIterator (const QgsFeatureRequest &request)
 base class constructor - stores the iteration parameters More...
 
virtual ~QgsAbstractFeatureIterator ()=default
 destructor makes sure that the iterator is closed properly More...
 
virtual bool close ()=0
 end of iterating: free the resources / lock More...
 
CompileStatus compileStatus () const
 Returns the status of expression compilation for filter expression requests. More...
 
virtual bool isValid () const
 Returns if this iterator is valid. More...
 
virtual bool nextFeature (QgsFeature &f)
 fetch next feature, return true on success More...
 
virtual bool rewind ()=0
 reset the iterator to the starting position More...
 
virtual void setInterruptionChecker (QgsFeedback *interruptionChecker)
 Attach an object that can be queried regularly by the iterator to check if it must stopped. More...
 

Protected Member Functions

void deref ()
 Remove reference, delete if refs == 0. More...
 
virtual bool fetchFeature (QgsFeature &f)=0
 If you write a feature iterator for your provider, this is the method you need to implement!! More...
 
QgsRectangle filterRectToSourceCrs (const QgsCoordinateTransform &transform) const
 Returns a rectangle representing the original request's QgsFeatureRequest::filterRect(). More...
 
void geometryToDestinationCrs (QgsFeature &feature, const QgsCoordinateTransform &transform) const
 Transforms feature's geometry according to the specified coordinate transform. More...
 
virtual bool nextFeatureFilterExpression (QgsFeature &f)
 By default, the iterator will fetch all features and check if the feature matches the expression. More...
 
virtual bool nextFeatureFilterFids (QgsFeature &f)
 By default, the iterator will fetch all features and check if the id is in the request. More...
 
virtual bool prepareSimplification (const QgsSimplifyMethod &simplifyMethod)
 Setup the simplification of geometries to fetch using the specified simplify method. More...
 
void ref ()
 Add reference. More...
 

Protected Attributes

bool mClosed = false
 Set to true, as soon as the iterator is closed. More...
 
CompileStatus mCompileStatus = NoCompilation
 Status of compilation of filter expression. More...
 
long mFetchedCount = 0
 Number of features already fetched by iterator. More...
 
QgsFeatureRequest mRequest
 A copy of the feature request. More...
 
bool mValid = true
 An invalid state of a feature iterator indicates that there was a problem with even getting it up and running. More...
 
bool mZombie = false
 A feature iterator may be closed already but still be serving features from the cache. More...
 
int refs = 0
 reference counting (to allow seamless copying of QgsFeatureIterator instances) TODO QGIS3: make this private More...
 

Friends

class QgsFeatureIterator
 

Detailed Description

Internal feature iterator to be implemented within data providers.

Definition at line 28 of file qgsfeatureiterator.h.

Member Enumeration Documentation

◆ CompileStatus

Status of expression compilation for filter expression requests.

Enumerator
NoCompilation 

Expression could not be compiled or not attempt was made to compile expression.

PartiallyCompiled 

Expression was partially compiled, but extra checks need to be applied to features.

Compiled 

Expression was fully compiled and delegated to data provider source.

Definition at line 33 of file qgsfeatureiterator.h.

Constructor & Destructor Documentation

◆ QgsAbstractFeatureIterator()

QgsAbstractFeatureIterator::QgsAbstractFeatureIterator ( const QgsFeatureRequest request)

base class constructor - stores the iteration parameters

Definition at line 22 of file qgsfeatureiterator.cpp.

◆ ~QgsAbstractFeatureIterator()

virtual QgsAbstractFeatureIterator::~QgsAbstractFeatureIterator ( )
virtualdefault

destructor makes sure that the iterator is closed properly

Member Function Documentation

◆ close()

virtual bool QgsAbstractFeatureIterator::close ( )
pure virtual

end of iterating: free the resources / lock

Implemented in QgsVectorLayerFeatureIterator, QgsCachedFeatureWriterIterator, and QgsCachedFeatureIterator.

◆ compileStatus()

CompileStatus QgsAbstractFeatureIterator::compileStatus ( ) const
inline

Returns the status of expression compilation for filter expression requests.

Since
QGIS 2.16

Definition at line 69 of file qgsfeatureiterator.h.

◆ deref()

void QgsAbstractFeatureIterator::deref ( )
protected

Remove reference, delete if refs == 0.

Definition at line 143 of file qgsfeatureiterator.cpp.

◆ fetchFeature()

virtual bool QgsAbstractFeatureIterator::fetchFeature ( QgsFeature f)
protectedpure virtual

If you write a feature iterator for your provider, this is the method you need to implement!!

Parameters
fThe feature to write to
Returns
true if a feature was written to f

Implemented in QgsVectorLayerFeatureIterator, QgsCachedFeatureWriterIterator, and QgsCachedFeatureIterator.

◆ filterRectToSourceCrs()

QgsRectangle QgsAbstractFeatureIterator::filterRectToSourceCrs ( const QgsCoordinateTransform transform) const
protected

Returns a rectangle representing the original request's QgsFeatureRequest::filterRect().

If transform is a valid coordinate transform, the return rectangle will represent the requested filterRect() transformed to the source's coordinate reference system. Iterators should call this method and use the returned rectangle for filtering features to ensure that any QgsFeatureRequest::destinationCrs() set on the request is respected. Will throw a QgsCsException if the rect cannot be transformed from the destination CRS.

Since
QGIS 3.0

Definition at line 118 of file qgsfeatureiterator.cpp.

◆ geometryToDestinationCrs()

void QgsAbstractFeatureIterator::geometryToDestinationCrs ( QgsFeature feature,
const QgsCoordinateTransform transform 
) const
protected

Transforms feature's geometry according to the specified coordinate transform.

If feature has no geometry or transform is invalid then calling this method has no effect and will be shortcut. Iterators should call this method before returning features to ensure that any QgsFeatureRequest::destinationCrs() set on the request is respected.

Since
QGIS 3.0

Definition at line 95 of file qgsfeatureiterator.cpp.

◆ isValid()

virtual bool QgsAbstractFeatureIterator::isValid ( ) const
inlinevirtual

Returns if this iterator is valid.

An invalid feature iterator is not able to provide a reliable source for data. If an iterator is invalid, either give up or try to send the request again (preferably after a timeout to give the system some time to stay responsive).

If you want to check if the iterator successfully completed, better use QgsFeatureIterator::isClosed().

Since
QGIS 3.0

Reimplemented in QgsVectorLayerFeatureIterator.

Definition at line 81 of file qgsfeatureiterator.h.

◆ nextFeature()

bool QgsAbstractFeatureIterator::nextFeature ( QgsFeature f)
virtual

fetch next feature, return true on success

Definition at line 27 of file qgsfeatureiterator.cpp.

◆ nextFeatureFilterExpression()

bool QgsAbstractFeatureIterator::nextFeatureFilterExpression ( QgsFeature f)
protectedvirtual

By default, the iterator will fetch all features and check if the feature matches the expression.

If you have a more sophisticated metodology (SQL request for the features...) and you check for the expression in your fetchFeature method, you can just redirect this call to fetchFeature so the default check will be omitted.

Parameters
fThe feature to write to
Returns
true if a feature was written to f

Reimplemented in QgsVectorLayerFeatureIterator.

Definition at line 74 of file qgsfeatureiterator.cpp.

◆ nextFeatureFilterFids()

bool QgsAbstractFeatureIterator::nextFeatureFilterFids ( QgsFeature f)
protectedvirtual

By default, the iterator will fetch all features and check if the id is in the request.

If you have a more sophisticated metodology (SQL request for the features...) and you are sure, that any feature you return from fetchFeature will match if the request was FilterFids you can just redirect this call to fetchFeature so the default check will be omitted.

Parameters
fThe feature to write to
Returns
true if a feature was written to f

Reimplemented in QgsCachedFeatureIterator.

Definition at line 85 of file qgsfeatureiterator.cpp.

◆ prepareSimplification()

bool QgsAbstractFeatureIterator::prepareSimplification ( const QgsSimplifyMethod simplifyMethod)
protectedvirtual

Setup the simplification of geometries to fetch using the specified simplify method.

Reimplemented in QgsVectorLayerFeatureIterator.

Definition at line 150 of file qgsfeatureiterator.cpp.

◆ ref()

void QgsAbstractFeatureIterator::ref ( )
protected

Add reference.

Definition at line 126 of file qgsfeatureiterator.cpp.

◆ rewind()

virtual bool QgsAbstractFeatureIterator::rewind ( )
pure virtual

reset the iterator to the starting position

Implemented in QgsVectorLayerFeatureIterator, QgsCachedFeatureWriterIterator, and QgsCachedFeatureIterator.

◆ setInterruptionChecker()

void QgsAbstractFeatureIterator::setInterruptionChecker ( QgsFeedback interruptionChecker)
virtual

Attach an object that can be queried regularly by the iterator to check if it must stopped.

This is mostly useful for iterators where a single nextFeature()/fetchFeature() iteration might be very long. A typical use case is the WFS provider. When nextFeature()/fetchFeature() is reasonably fast, it is not necessary to implement this method. The default implementation does nothing.

Since
QGIS 2.16
Note
not available in Python bindings

Reimplemented in QgsVectorLayerFeatureIterator.

Definition at line 214 of file qgsfeatureiterator.cpp.

Friends And Related Function Documentation

◆ QgsFeatureIterator

friend class QgsFeatureIterator
friend

Definition at line 168 of file qgsfeatureiterator.h.

Member Data Documentation

◆ mClosed

bool QgsAbstractFeatureIterator::mClosed = false
protected

Set to true, as soon as the iterator is closed.

Definition at line 148 of file qgsfeatureiterator.h.

◆ mCompileStatus

CompileStatus QgsAbstractFeatureIterator::mCompileStatus = NoCompilation
protected

Status of compilation of filter expression.

Definition at line 174 of file qgsfeatureiterator.h.

◆ mFetchedCount

long QgsAbstractFeatureIterator::mFetchedCount = 0
protected

Number of features already fetched by iterator.

Definition at line 171 of file qgsfeatureiterator.h.

◆ mRequest

QgsFeatureRequest QgsAbstractFeatureIterator::mRequest
protected

A copy of the feature request.

Definition at line 145 of file qgsfeatureiterator.h.

◆ mValid

bool QgsAbstractFeatureIterator::mValid = true
protected

An invalid state of a feature iterator indicates that there was a problem with even getting it up and running.

This should be set to false by subclasses if they have problems connecting to the provider. Do NOT set this to false when the feature iterator closes or has no features but we are sure, that it's just an empty dataset.

Definition at line 187 of file qgsfeatureiterator.h.

◆ mZombie

bool QgsAbstractFeatureIterator::mZombie = false
protected

A feature iterator may be closed already but still be serving features from the cache.

This is done when we serve features which have been pre-fetched and the order by has been locally sorted. In such a scenario, all resources have been released (mClosed is true) but the deads are still alive.

Definition at line 157 of file qgsfeatureiterator.h.

◆ refs

int QgsAbstractFeatureIterator::refs = 0
protected

reference counting (to allow seamless copying of QgsFeatureIterator instances) TODO QGIS3: make this private

Definition at line 163 of file qgsfeatureiterator.h.


The documentation for this class was generated from the following files: