QGIS API Documentation  3.37.0-Master (a5b4d9743e8)
Public Member Functions | Properties | List of all members
QgsFeature Class Reference

The feature class encapsulates a single feature including its unique ID, geometry and a list of field/values attributes. More...

#include <qgsfeature.h>

Public Member Functions

 QgsFeature (const QgsFeature &rhs)
 Copy constructor. More...
 
 QgsFeature (const QgsFields &fields, QgsFeatureId id=FID_NULL)
 Constructor for QgsFeature. More...
 
 QgsFeature (QgsFeatureId id=FID_NULL)
 Constructor for QgsFeature. More...
 
virtual ~QgsFeature ()
 
int approximateMemoryUsage () const
 Returns the approximate RAM usage of the feature, in bytes. More...
 
QVariant attribute (const QString &name) const
 Lookup attribute value by attribute name. More...
 
QVariant attribute (int fieldIdx) const
 Lookup attribute value from its index. More...
 
int attributeCount () const
 Returns the number of attributes attached to the feature. More...
 
QVariantMap attributeMap () const
 Returns the feature's attributes as a map of field name to value. More...
 
QgsAttributes attributes () const
 Returns the feature's attributes. More...
 
void clearGeometry ()
 Removes any geometry associated with the feature. More...
 
bool deleteAttribute (const QString &name)
 Clear's an attribute's value by its field name. More...
 
void deleteAttribute (int field)
 Clear's an attribute's value by its index. More...
 
const QgsSymbolembeddedSymbol () const
 Returns the feature's embedded symbology, or nullptr if the feature has no embedded symbol. More...
 
int fieldNameIndex (const QString &fieldName) const
 Utility method to get attribute index from name. More...
 
QgsFields fields () const
 Returns the field map associated with the feature. More...
 
QgsGeometry geometry () const
 Returns the geometry associated with this feature. More...
 
bool hasGeometry () const
 Returns true if the feature has an associated geometry. More...
 
QgsFeatureId id () const
 Returns the feature ID for this feature. More...
 
void initAttributes (int fieldCount)
 Initialize this feature with the given number of fields. More...
 
bool isUnsetValue (int fieldIdx) const
 Returns true if the attribute at the specified index is an unset value. More...
 
bool isValid () const
 Returns the validity of this feature. More...
 
 operator QVariant () const
 Allows direct construction of QVariants from features. More...
 
bool operator!= (const QgsFeature &other) const
 Compares two features. More...
 
QgsFeatureoperator= (const QgsFeature &rhs)
 Assignment operator. More...
 
bool operator== (const QgsFeature &other) const
 Compares two features. More...
 
void padAttributes (int count)
 Resizes the attributes attached to this feature by appending the specified count of NULL values to the end of the existing attributes. More...
 
void resizeAttributes (int fieldCount)
 Resizes the attributes attached to this feature to the given number of fields. More...
 
bool setAttribute (const QString &name, const QVariant &value)
 Insert a value into attribute, by field name. More...
 
bool setAttribute (int field, const QVariant &attr)
 Sets an attribute's value by field index. More...
 
void setAttributes (const QgsAttributes &attrs)
 Sets the feature's attributes. More...
 
void setEmbeddedSymbol (QgsSymbol *symbol)
 Sets the feature's embedded symbol. More...
 
void setFields (const QgsFields &fields, bool initAttributes=false)
 Assigns a field map with the feature to allow attribute access by attribute name. More...
 
void setGeometry (const QgsGeometry &geometry)
 Set the feature's geometry. More...
 
void setGeometry (std::unique_ptr< QgsAbstractGeometry > geometry)
 Set the feature's geometry. More...
 
void setId (QgsFeatureId id)
 Sets the feature id for this feature. More...
 
void setValid (bool validity)
 Sets the validity of the feature. More...
 

Properties

QgsAttributes attributes
 
QgsFields fields
 
QgsGeometry geometry
 
Q_GADGET QgsFeatureId id
 

Detailed Description

The feature class encapsulates a single feature including its unique ID, geometry and a list of field/values attributes.

Note
QgsFeature objects are implicitly shared.

Definition at line 55 of file qgsfeature.h.

Constructor & Destructor Documentation

◆ QgsFeature() [1/3]

QgsFeature::QgsFeature ( QgsFeatureId  id = FID_NULL)

Constructor for QgsFeature.

Parameters
idunique feature ID

Definition at line 39 of file qgsfeature.cpp.

◆ QgsFeature() [2/3]

QgsFeature::QgsFeature ( const QgsFields fields,
QgsFeatureId  id = FID_NULL 
)

Constructor for QgsFeature.

Parameters
fieldsfeature's fields
idunique feature ID

Definition at line 44 of file qgsfeature.cpp.

◆ QgsFeature() [3/3]

QgsFeature::QgsFeature ( const QgsFeature rhs)

Copy constructor.

Definition at line 51 of file qgsfeature.cpp.

◆ ~QgsFeature()

QgsFeature::~QgsFeature ( )
virtual

Definition at line 90 of file qgsfeature.cpp.

Member Function Documentation

◆ approximateMemoryUsage()

int QgsFeature::approximateMemoryUsage ( ) const

Returns the approximate RAM usage of the feature, in bytes.

This method takes into account the size of variable elements (strings, geometry, ...), but the value returned should be considered as a lower bound estimation.

Since
QGIS 3.16

Definition at line 382 of file qgsfeature.cpp.

◆ attribute() [1/2]

QVariant QgsFeature::attribute ( const QString &  name) const

Lookup attribute value by attribute name.

Field map must be associated using setFields() before this method can be used.

Parameters
nameThe name of the attribute to get
Returns
The value of the attribute, or an invalid/null variant if no such name exists
See also
setFields

Definition at line 335 of file qgsfeature.cpp.

◆ attribute() [2/2]

QVariant QgsFeature::attribute ( int  fieldIdx) const

Lookup attribute value from its index.

Parameters
fieldIdxThe index of the attribute to get
Returns
The value of the attribute, or an invalid/null variant if no such name exists
See also
setFields()

Definition at line 305 of file qgsfeature.cpp.

◆ attributeCount()

int QgsFeature::attributeCount ( ) const

Returns the number of attributes attached to the feature.

Since
QGIS 3.18

Definition at line 155 of file qgsfeature.cpp.

◆ attributeMap()

QVariantMap QgsFeature::attributeMap ( ) const

Returns the feature's attributes as a map of field name to value.

Note
The fields definition must be associated with the feature using setFields() before this method can be used.
See also
attributes()
setAttributes()
Since
QGIS 3.22.2

Definition at line 137 of file qgsfeature.cpp.

◆ attributes()

QgsAttributes QgsFeature::attributes ( ) const

Returns the feature's attributes.

Alternatively, in Python it is possible to directly iterate over a feature in order to retrieve its attributes:

feature = QgsFeature()
feature.setAttributes([11, 'string value', 55.5])
for attr in feature:
print(attr)
The feature class encapsulates a single feature including its unique ID, geometry and a list of field...
Definition: qgsfeature.h:56
See also
setAttributes()
attributeMap()

Definition at line 132 of file qgsfeature.cpp.

◆ clearGeometry()

void QgsFeature::clearGeometry ( )

Removes any geometry associated with the feature.

See also
setGeometry()
hasGeometry()

Definition at line 181 of file qgsfeature.cpp.

◆ deleteAttribute() [1/2]

bool QgsFeature::deleteAttribute ( const QString &  name)

Clear's an attribute's value by its field name.

Field map must be associated using setFields() before this method can be used.

Parameters
nameThe name of the field to clear
Returns
false if attribute name could not be converted to index
See also
setFields()

Definition at line 294 of file qgsfeature.cpp.

◆ deleteAttribute() [2/2]

void QgsFeature::deleteAttribute ( int  field)

Clear's an attribute's value by its index.

Parameters
fieldthe index of the field
See also
setAttribute()

Definition at line 105 of file qgsfeature.cpp.

◆ embeddedSymbol()

const QgsSymbol * QgsFeature::embeddedSymbol ( ) const

Returns the feature's embedded symbology, or nullptr if the feature has no embedded symbol.

Since
QGIS 3.20

Definition at line 321 of file qgsfeature.cpp.

◆ fieldNameIndex()

int QgsFeature::fieldNameIndex ( const QString &  fieldName) const

Utility method to get attribute index from name.

Field map must be associated using setFields() before this method can be used.

Parameters
fieldNamename of field to get attribute index of
Returns
-1 if field does not exist or field map is not associated.
See also
setFields()

Definition at line 350 of file qgsfeature.cpp.

◆ fields()

QgsFields QgsFeature::fields ( ) const

Returns the field map associated with the feature.

See also
setFields()

Definition at line 205 of file qgsfeature.cpp.

◆ geometry()

QgsGeometry QgsFeature::geometry ( ) const

Returns the geometry associated with this feature.

If the feature has no geometry, an empty QgsGeometry object will be returned.

See also
hasGeometry()
setGeometry()

Definition at line 111 of file qgsfeature.cpp.

◆ hasGeometry()

bool QgsFeature::hasGeometry ( ) const

Returns true if the feature has an associated geometry.

See also
geometry()

Definition at line 230 of file qgsfeature.cpp.

◆ id()

QgsFeatureId QgsFeature::id ( ) const

Returns the feature ID for this feature.

See also
setId()

Definition at line 100 of file qgsfeature.cpp.

◆ initAttributes()

void QgsFeature::initAttributes ( int  fieldCount)

Initialize this feature with the given number of fields.

Discards any previously set attribute data.

Parameters
fieldCountNumber of fields to initialize
See also
resizeAttributes()

Definition at line 235 of file qgsfeature.cpp.

◆ isUnsetValue()

bool QgsFeature::isUnsetValue ( int  fieldIdx) const

Returns true if the attribute at the specified index is an unset value.

See also
QgsUnsetAttributeValue
Since
QGIS 3.28

Definition at line 313 of file qgsfeature.cpp.

◆ isValid()

bool QgsFeature::isValid ( ) const

Returns the validity of this feature.

This is normally set by the provider to indicate some problem that makes the feature invalid or to indicate a null feature.

See also
setValid()

Definition at line 216 of file qgsfeature.cpp.

◆ operator QVariant()

QgsFeature::operator QVariant ( ) const
inline

Allows direct construction of QVariants from features.

Definition at line 885 of file qgsfeature.h.

◆ operator!=()

bool QgsFeature::operator!= ( const QgsFeature other) const

Compares two features.

Definition at line 85 of file qgsfeature.cpp.

◆ operator=()

QgsFeature & QgsFeature::operator= ( const QgsFeature rhs)

Assignment operator.

Definition at line 56 of file qgsfeature.cpp.

◆ operator==()

bool QgsFeature::operator== ( const QgsFeature other) const

Compares two features.

Definition at line 62 of file qgsfeature.cpp.

◆ padAttributes()

void QgsFeature::padAttributes ( int  count)

Resizes the attributes attached to this feature by appending the specified count of NULL values to the end of the existing attributes.

See also
resizeAttributes()
Since
QGIS 3.18

Definition at line 253 of file qgsfeature.cpp.

◆ resizeAttributes()

void QgsFeature::resizeAttributes ( int  fieldCount)

Resizes the attributes attached to this feature to the given number of fields.

If the new fieldCount is greater than the original number of fields then the additional attributes will be filled with NULL values. All existing attributes will remain unchanged.

If the new fieldCount is less than the original number of fields then the unwanted values will be discarded from the end of the existing attributes.

See also
initAttributes()
padAttributes()
Since
QGIS 3.18

Definition at line 244 of file qgsfeature.cpp.

◆ setAttribute() [1/2]

bool QgsFeature::setAttribute ( const QString &  name,
const QVariant &  value 
)

Insert a value into attribute, by field name.

Returns false if field name could not be matched.

Field map must be associated using setFields() before this method can be used.

Calling this method will automatically set the feature as valid (see isValid()).

Parameters
nameThe name of the field to set
valueThe value to set
Returns
false if attribute name could not be converted to index
See also
setFields()

Definition at line 282 of file qgsfeature.cpp.

◆ setAttribute() [2/2]

bool QgsFeature::setAttribute ( int  field,
const QVariant &  attr 
)

Sets an attribute's value by field index.

If the attribute was successfully set then the feature will be automatically marked as valid (see isValid()).

Parameters
fieldthe index of the field to set
attrthe value of the attribute
Returns
false, if the field index does not exist
See also
setAttributes()

Definition at line 262 of file qgsfeature.cpp.

◆ setAttributes()

void QgsFeature::setAttributes ( const QgsAttributes attrs)

Sets the feature's attributes.

Calling this method will automatically set the feature as valid (see isValid()).

The number of provided attributes need to exactly match the number of the feature's fields.

Parameters
attrsList of attribute values
Warning
If the number of provided attributes does not exactly match the number of the feature's fields then it will not be possible to add this feature to the corresponding data provider.
See also
setAttribute()
attributes()

Definition at line 160 of file qgsfeature.cpp.

◆ setEmbeddedSymbol()

void QgsFeature::setEmbeddedSymbol ( QgsSymbol symbol)

Sets the feature's embedded symbol.

Ownership of symbol is transferred to the feature.

Since
QGIS 3.20

Definition at line 326 of file qgsfeature.cpp.

◆ setFields()

void QgsFeature::setFields ( const QgsFields fields,
bool  initAttributes = false 
)

Assigns a field map with the feature to allow attribute access by attribute name.

Parameters
fieldsThe attribute fields which this feature holds
initAttributesIf true, attributes are initialized. Clears any data previously assigned.
See also
fields()

Definition at line 195 of file qgsfeature.cpp.

◆ setGeometry() [1/2]

void QgsFeature::setGeometry ( const QgsGeometry geometry)

Set the feature's geometry.

Calling this method will automatically set the feature as valid (see isValid()).

Parameters
geometrynew feature geometry
See also
geometry()
clearGeometry()

Definition at line 167 of file qgsfeature.cpp.

◆ setGeometry() [2/2]

void QgsFeature::setGeometry ( std::unique_ptr< QgsAbstractGeometry geometry)

Set the feature's geometry.

Ownership of the geometry is transferred to the feature.

Calling this method will automatically set the feature as valid (see isValid()).

This method is a shortcut for calling:

feature.setGeometry( QgsGeometry( geometry ) )
A geometry is the spatial representation of a feature.
Definition: qgsgeometry.h:162

Example

# Sets a feature's geometry to a point geometry
feature.setGeometry( QgsPoint( 210, 41 ) )
print(feature.geometry())
# output: <QgsGeometry: Point (210 41)>
# Sets a feature's geometry to a line string
feature.setGeometry( QgsLineString( [ QgsPoint( 210, 41 ), QgsPoint( 301, 55 ) ] ) )
print(feature.geometry())
# output: <QgsGeometry: LineString (210 41, 301 55)>
Line string geometry type, with support for z-dimension and m-values.
Definition: qgslinestring.h:45
Point geometry type, with support for z-dimension and m-values.
Definition: qgspoint.h:49
See also
geometry()
clearGeometry()
Since
QGIS 3.6

Definition at line 174 of file qgsfeature.cpp.

◆ setId()

void QgsFeature::setId ( QgsFeatureId  id)

Sets the feature id for this feature.

Parameters
idfeature id
See also
id()
Warning
Feature IDs will be automatically changed whenever a feature is added to vector layer or data provider. This method is not designed to allow a specific feature ID to be assigned to a feature which will be added to a layer or data provider, and the results will be unpredictable

Definition at line 122 of file qgsfeature.cpp.

◆ setValid()

void QgsFeature::setValid ( bool  validity)

Sets the validity of the feature.

Parameters
validityset to true if feature is valid
See also
isValid()

Definition at line 221 of file qgsfeature.cpp.

Property Documentation

◆ attributes

QgsAttributes QgsFeature::attributes
readwrite

Definition at line 62 of file qgsfeature.h.

◆ fields

QgsFields QgsFeature::fields
readwrite

Definition at line 62 of file qgsfeature.h.

◆ geometry

QgsGeometry QgsFeature::geometry
readwrite

Definition at line 62 of file qgsfeature.h.

◆ id

Q_GADGET QgsFeatureId QgsFeature::id
readwrite

Definition at line 62 of file qgsfeature.h.


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