QGIS API Documentation 3.28.0-Firenze (ed3ad0430f)
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...
 
enum class  RequestToSourceCrsResult : int { Success , DistanceWithinMustBeCheckedManually }
 Possible results from the updateRequestToSourceCrs() method. 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...
 
bool compileFailed () const
 Indicator if there was an error when sending the compiled query to the server. 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 SIP_THROW(QgsCsException)
 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...
 
RequestToSourceCrsResult updateRequestToSourceCrs (QgsFeatureRequest &request, const QgsCoordinateTransform &transform) const SIP_THROW(QgsCsException)
 Update a QgsFeatureRequest so that spatial filters are transformed to the source's coordinate reference system. More...
 

Protected Attributes

bool mClosed = false
 Sets to true, as soon as the iterator is closed. More...
 
bool mCompileFailed = false
 
CompileStatus mCompileStatus = NoCompilation
 Status of compilation of filter expression. More...
 
long 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) 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.

◆ RequestToSourceCrsResult

Possible results from the updateRequestToSourceCrs() method.

Since
QGIS 3.22
Enumerator
Success 

Request was successfully updated to the source CRS, or no changes were required.

DistanceWithinMustBeCheckedManually 

The distance within request cannot be losslessly updated to the source CRS, and callers will need to take appropriate steps to handle the distance within requirement manually during feature iteration.

Definition at line 99 of file qgsfeatureiterator.h.

Constructor & Destructor Documentation

◆ QgsAbstractFeatureIterator()

QgsAbstractFeatureIterator::QgsAbstractFeatureIterator ( const QgsFeatureRequest request)

base class constructor - stores the iteration parameters

Definition at line 25 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 QgsCachedFeatureIterator, QgsCachedFeatureWriterIterator, and QgsVectorLayerFeatureIterator.

◆ compileFailed()

bool QgsAbstractFeatureIterator::compileFailed ( ) const

Indicator if there was an error when sending the compiled query to the server.

This indicates that there is something wrong with the expression compiler.

Since
QGIS 3.2

Definition at line 191 of file qgsfeatureiterator.cpp.

◆ 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 184 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 QgsCachedFeatureIterator, QgsCachedFeatureWriterIterator, and QgsVectorLayerFeatureIterator.

◆ 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 157 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 101 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 30 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 80 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 91 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 196 of file qgsfeatureiterator.cpp.

◆ ref()

void QgsAbstractFeatureIterator::ref ( )
protected

Add reference.

Definition at line 167 of file qgsfeatureiterator.cpp.

◆ rewind()

virtual bool QgsAbstractFeatureIterator::rewind ( )
pure virtual

reset the iterator to the starting position

Implemented in QgsCachedFeatureIterator, QgsCachedFeatureWriterIterator, and QgsVectorLayerFeatureIterator.

◆ 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.

Note
not available in Python bindings
Since
QGIS 2.16

Reimplemented in QgsVectorLayerFeatureIterator.

Definition at line 261 of file qgsfeatureiterator.cpp.

◆ updateRequestToSourceCrs()

QgsAbstractFeatureIterator::RequestToSourceCrsResult QgsAbstractFeatureIterator::updateRequestToSourceCrs ( QgsFeatureRequest request,
const QgsCoordinateTransform transform 
) const
protected

Update a QgsFeatureRequest so that spatial filters are transformed to the source's coordinate reference system.

Iterators should call this method against the request used for filtering features to ensure that any QgsFeatureRequest::destinationCrs() set on the request is respected.

Returns
result of operation. See QgsAbstractFeatureIterator::RequestToSourceCrsResult for interpretation.
Exceptions
QgsCsExceptionif the rect cannot be transformed from the destination CRS.
Since
QGIS 3.22

Definition at line 124 of file qgsfeatureiterator.cpp.

Friends And Related Function Documentation

◆ QgsFeatureIterator

friend class QgsFeatureIterator
friend

Definition at line 202 of file qgsfeatureiterator.h.

Member Data Documentation

◆ mClosed

bool QgsAbstractFeatureIterator::mClosed = false
protected

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

Definition at line 181 of file qgsfeatureiterator.h.

◆ mCompileFailed

bool QgsAbstractFeatureIterator::mCompileFailed = false
protected

Definition at line 210 of file qgsfeatureiterator.h.

◆ mCompileStatus

CompileStatus QgsAbstractFeatureIterator::mCompileStatus = NoCompilation
protected

Status of compilation of filter expression.

Definition at line 208 of file qgsfeatureiterator.h.

◆ mFetchedCount

long long QgsAbstractFeatureIterator::mFetchedCount = 0
protected

Number of features already fetched by iterator.

Definition at line 205 of file qgsfeatureiterator.h.

◆ mRequest

QgsFeatureRequest QgsAbstractFeatureIterator::mRequest
protected

A copy of the feature request.

Definition at line 178 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 223 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 190 of file qgsfeatureiterator.h.

◆ refs

int QgsAbstractFeatureIterator::refs = 0
protected

reference counting (to allow seamless copying of QgsFeatureIterator instances)

Definition at line 197 of file qgsfeatureiterator.h.


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