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

#include <qgsfeatureiterator.h>

Inheritance diagram for QgsAbstractFeatureIterator:

[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

virtual	~QgsAbstractFeatureIterator ()=default
	destructor makes sure that the iterator is closed properly

virtual bool	close ()=0
	Call to end the iteration.

bool	compileFailed () const
	Indicator if there was an error when sending the compiled query to the server.

CompileStatus	compileStatus () const
	Returns the status of expression compilation for filter expression requests.

virtual bool	isValid () const
	Returns if this iterator is valid.

virtual bool	nextFeature (QgsFeature &f)
	Fetch next feature and stores in f, returns `true` on success.

virtual bool	rewind ()=0
	Resets the iterator to the starting position.

virtual void	setInterruptionChecker (QgsFeedback *interruptionChecker)
	Attach an object that can be queried regularly by the iterator to check if it must stopped.

Protected Member Functions
void	deref ()
	Remove reference, delete if refs == 0.

virtual bool	fetchFeature (QgsFeature &f)=0
	If you write a feature iterator for your provider, this is the method you need to implement!!

QgsRectangle	filterRectToSourceCrs (const QgsCoordinateTransform &transform) const
	Returns a rectangle representing the original request's QgsFeatureRequest::filterRect().

void	geometryToDestinationCrs (QgsFeature &feature, const QgsCoordinateTransform &transform) const
	Transforms feature's geometry according to the specified coordinate transform.

virtual bool	nextFeatureFilterExpression (QgsFeature &f)
	By default, the iterator will fetch all features and check if the feature matches the expression.

virtual bool	nextFeatureFilterFids (QgsFeature &f)
	By default, the iterator will fetch all features and check if the id is in the request.

virtual bool	prepareSimplification (const QgsSimplifyMethod &simplifyMethod)
	Setup the simplification of geometries to fetch using the specified simplify method.

void	ref ()
	Add reference.

RequestToSourceCrsResult	updateRequestToSourceCrs (QgsFeatureRequest &request, const QgsCoordinateTransform &transform) const
	Update a QgsFeatureRequest so that spatial filters are transformed to the source's coordinate reference system.

Protected Attributes
bool	mClosed = false
	Sets to `true`, as soon as the iterator is closed.

bool	mCompileFailed = false

CompileStatus	mCompileStatus = NoCompilation
	Status of compilation of filter expression.

long long	mFetchedCount = 0
	Number of features already fetched by iterator.

QgsFeatureRequest	mRequest
	A copy of the feature request.

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

bool	mZombie = false
	A feature iterator may be closed already but still be serving features from the cache.

int	refs = 0
	reference counting (to allow seamless copying of QgsFeatureIterator instances)

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

enum QgsAbstractFeatureIterator::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

enum class QgsAbstractFeatureIterator::RequestToSourceCrsResult : int

strong

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 103 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

Call to end the iteration.

This frees any resources used by the iterator.

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 189 of file qgsfeatureiterator.cpp.

◆ compileStatus()

CompileStatus QgsAbstractFeatureIterator::compileStatus ( ) const

inline

Returns the status of expression compilation for filter expression requests.

Definition at line 74 of file qgsfeatureiterator.h.

◆ deref()

void QgsAbstractFeatureIterator::deref ( )

protected

Remove reference, delete if refs == 0.

Definition at line 182 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

f	The 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.

Definition at line 155 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.

Definition at line 98 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().

Reimplemented in QgsVectorLayerFeatureIterator.

Definition at line 85 of file qgsfeatureiterator.h.

◆ nextFeature()

bool QgsAbstractFeatureIterator::nextFeature ( QgsFeature & f )

virtual

Fetch next feature and stores in f, returns 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

f	The feature to write to

Returns: true if a feature was written to f

Reimplemented in QgsVectorLayerFeatureIterator.

Definition at line 77 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

f	The feature to write to

Returns: true if a feature was written to f

Reimplemented in QgsCachedFeatureIterator.

Definition at line 88 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 194 of file qgsfeatureiterator.cpp.

◆ ref()

void QgsAbstractFeatureIterator::ref ( )

protected

Add reference.

Definition at line 165 of file qgsfeatureiterator.cpp.

◆ rewind()

virtual bool QgsAbstractFeatureIterator::rewind ( )

pure virtual

Resets 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

Reimplemented in QgsVectorLayerFeatureIterator.

Definition at line 259 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

QgsCsException if the rect cannot be transformed from the destination CRS.

Since: QGIS 3.22

Definition at line 121 of file qgsfeatureiterator.cpp.

Friends And Related Symbol Documentation

◆ QgsFeatureIterator

friend class QgsFeatureIterator

friend

Definition at line 204 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 183 of file qgsfeatureiterator.h.

◆ mCompileFailed

bool QgsAbstractFeatureIterator::mCompileFailed = false

protected

Definition at line 212 of file qgsfeatureiterator.h.

◆ mCompileStatus

CompileStatus QgsAbstractFeatureIterator::mCompileStatus = NoCompilation

protected

Status of compilation of filter expression.

Definition at line 210 of file qgsfeatureiterator.h.

◆ mFetchedCount

long long QgsAbstractFeatureIterator::mFetchedCount = 0

protected

Number of features already fetched by iterator.

Definition at line 207 of file qgsfeatureiterator.h.

◆ mRequest

QgsFeatureRequest QgsAbstractFeatureIterator::mRequest

protected

A copy of the feature request.

Definition at line 180 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 225 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 192 of file qgsfeatureiterator.h.

◆ refs

int QgsAbstractFeatureIterator::refs = 0

protected

reference counting (to allow seamless copying of QgsFeatureIterator instances)

Definition at line 199 of file qgsfeatureiterator.h.

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

/build/qgis-3.40.0+99sid/src/core/qgsfeatureiterator.h
/build/qgis-3.40.0+99sid/src/core/qgsfeatureiterator.cpp

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Enumeration Documentation

◆ CompileStatus

◆ RequestToSourceCrsResult

Constructor & Destructor Documentation

◆ QgsAbstractFeatureIterator()

◆ ~QgsAbstractFeatureIterator()

Member Function Documentation

◆ close()

◆ compileFailed()

◆ compileStatus()

◆ deref()

◆ fetchFeature()

◆ filterRectToSourceCrs()

◆ geometryToDestinationCrs()

◆ isValid()

◆ nextFeature()

◆ nextFeatureFilterExpression()

◆ nextFeatureFilterFids()

◆ prepareSimplification()

◆ ref()

◆ rewind()

◆ setInterruptionChecker()

◆ updateRequestToSourceCrs()

Friends And Related Symbol Documentation

◆ QgsFeatureIterator

Member Data Documentation

◆ mClosed

◆ mCompileFailed

◆ mCompileStatus

◆ mFetchedCount

◆ mRequest

◆ mValid

◆ mZombie

◆ refs