Skip to content

Commit

Permalink
Implicit sharing for QgsFeature
Browse files Browse the repository at this point in the history
  • Loading branch information
@nyalldawson
nyalldawson committed May 20, 2015
1 parent c33b9fa commit 267d952
Show file tree
Hide file tree
Showing 5 changed files with 423 additions and 276 deletions.
188 changes: 114 additions & 74 deletions python/core/qgsfeature.sip
View file
Expand Up @@ -104,7 +104,7 @@ typedef QMap<int, QgsField> QgsFieldMap;
/** \ingroup core
* The feature class encapsulates a single feature including its id,
* geometry and a list of field/values attributes.
*
* \note QgsFeature objects are implicitly shared.
* @author Gary E.Sherman
*/
class QgsFeature
Expand Down Expand Up @@ -218,42 +218,57 @@ class QgsFeature
sipCpp->deleteAttribute(fieldIdx);
%End

//! Constructor
/** Constructor for QgsFeature
* @param id feature id
*/
QgsFeature( qint64 id = 0 );

/** Constructor for QgsFeature
* @param fields feature's fields
* @param id feature id
*/
QgsFeature( const QgsFields& fields, qint64 id = 0 );

/** copy ctor needed due to internal pointer */
/** Copy constructor
*/
QgsFeature( const QgsFeature & rhs );

//! Destructor
~QgsFeature();

/**
* Get the feature id for this feature
* @return Feature id
/** Get the feature ID for this feature.
* @returns feature ID
* @see setFeatureId
*/
qint64 id() const;

/**
* Set the feature id for this feature
* @param id Feature id
/** Sets the feature ID for this feature.
* @param id feature id
* @see id
*/
void setFeatureId( qint64 id );

/** Returns the feature's attributes.
* @link attributes @endlink method.
* @returns list of feature's attributes
* @see setAttributes
* @note added in QGIS 2.9
*/
QgsAttributes attributes() const;

/** Sets the feature's attributes.
* @param attrs attribute list
* @see setAttribute
* @see attributes
*/
void setAttributes( const QgsAttributes& attrs );

/**
* Set an attribute by id
*
* @param field The index of the field to set
* @param attr The value of the attribute
*
* @return false, if the field id does not exist
*
/** Set an attribute's value by field index.
* @param field the index of the field to set
* @param attr the value of the attribute
* @return false, if the field index does not exist
* @note For Python: raises a KeyError exception instead of returning false
* @see setAttributes
*/
bool setAttribute( int field, const QVariant& attr /GetWrapper/);
%MethodCode
Expand All @@ -275,17 +290,14 @@ class QgsFeature
}
%End

/**
* Initialize this feature with the given number of fields. Discard any previously set attribute data.
/** Initialize this feature with the given number of fields. Discard any previously set attribute data.
* @param fieldCount Number of fields to initialize
*/
void initAttributes( int fieldCount );

/**
* Deletes an attribute and its value
*
* @param field The index of the field
*
/** Deletes an attribute and its value.
* @param field the index of the field
* @see setAttribute
* @note For Python: raises a KeyError exception if the field is not found
*/
void deleteAttribute( int field );
Expand All @@ -298,92 +310,123 @@ class QgsFeature
sipIsErr = 1;
}
%End
/**
* Return the validity of this feature. This is normally set by
/** 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 setValid
*/
bool isValid() const;

/**
* Set the validity of the feature.
/** Sets the validity of the feature.
* @param validity set to true if feature is valid
* @see isValid
*/
void setValid( bool validity );

/**
* Get the geometry object associated with this feature
/** Get the geometry object associated with this feature. If the geometry
* is not going to be modified than calling the const @link constGeometry @endlink
* method is preferable as it avoids a potentially expensive detach operation.
*
* It is possible to modify the geometry in place but this will
* be removed in 3.0 and therefore @link setGeometry @endlink should be called explicitly.
*
* @note will be modified to return by value in QGIS 3.0: `QgsGeometry geometry() const;`
*
* @returns pointer to feature's geometry
* @see constGeometry
* @see geometryAndOwnership
* @see setGeometry
*/
QgsGeometry* geometry();

/** Gets a const pointer to the geometry object associated with this feature.
/** Gets a const pointer to the geometry object associated with this feature. If the geometry
* is not going to be modified than this method is preferable to the non-const
* @link geometry @endlink method.
* @note this is a temporary method for 2.x release cycle. Will be removed in QGIS 3.0.
* @returns const pointer to feature's geometry
* @see geometry
* @see geometryAndOwnership
* @see setGeometry
* @note added in QGIS 2.9
* @note will be removed in QGIS 3.0
*/
const QgsGeometry* constGeometry() const;

/**
* Get the geometry object associated with this feature
* The caller assumes responsibility for the QgsGeometry*'s destruction.
* @deprecated will be removed in QGIS 3.0
/** Get the geometry object associated with this feature, and transfer ownership of the
* geometry to the caller. The caller assumes responsibility for the QgsGeometry*'s destruction.
* @returns pointer to feature's geometry
* @see geometry
* @see setGeometry
*/
QgsGeometry *geometryAndOwnership() /Factory,Deprecated/;

/** Set this feature's geometry from another QgsGeometry object (deep copy)
/** Set this feature's geometry from another QgsGeometry object. This method performs a deep copy
* of the geometry.
* @param geom new feature geometry
* @see geometry
* @see constGeometry
* @see geometryAndOwnership
* @see setGeometryAndOwnership
*/
void setGeometry( const QgsGeometry& geom );

/** Set this feature's geometry (takes geometry ownership)
*
/** Set this feature's geometry from a QgsGeometry pointer. Ownership of the geometry is transferred
* to the feature.
* @param geom new feature geometry
* @note not available in python bindings
* @see geometry
* @see constGeometry
* @see geometryAndOwnership
* @see setGeometryAndOwnership
* @deprecated will be removed in QGIS 3.0
*/
// void setGeometry( QgsGeometry* geom /Transfer/ );

/**
* Set this feature's geometry from WKB
*
* This feature assumes responsibility for destroying geom.
*
/** Set this feature's geometry from WKB. This feature assumes responsibility for destroying the
* created geometry.
* @param geom geometry as WKB
* @param length size of WKB
* @see setGeometry
* @see geometry
* @see constGeometry
* @see geometryAndOwnership
* @deprecated will be removed in QGIS 3.0
*/
void setGeometryAndOwnership( unsigned char * geom /Transfer/, size_t length );

/** Assign a field map with the feature to allow attribute access by attribute name
*
* @param fields The attribute fields which this feature holds. When used from python, make sure
* a copy of the fields is held by python, as ownership stays there.
* I.e. Do not call feature.setFields( myDataProvider.fields() ) but instead call
* myFields = myDataProvider.fields()
* feature.setFields( myFields )
/** Assign a field map with the feature to allow attribute access by attribute name.
* @param fields The attribute fields which this feature holds
* @param initAttributes If true, attributes are initialized. Clears any data previously assigned.
* C++: Defaults to false
* Python: Defaults to true
*
* TODO: QGIS3 - take reference, not pointer
* @deprecated use setFields( const QgsFields& fields, bool initAttributes = false ) instead
* @note not available in Python bindings
*/
void setFields( const QgsFields* fields, bool initAttributes = true );
//void setFields( const QgsFields* fields, bool initAttributes = true );

/** Get associated field map.
*
* TODO: QGIS 3 - return reference or value, not pointer
/** Assign a field map with the feature to allow attribute access by attribute name.
* @param fields The attribute fields which this feature holds
* @param initAttributes If true, attributes are initialized. Clears any data previously assigned.
* C++: Defaults to false
* Python: Defaults to true
* @note added in QGIS 2.9
* @see fields
*/
void setFields( const QgsFields& fields, bool initAttributes = true );

/** Returns the field map associated with the feature.
* @see setFields
* TODO: QGIS 3 - return value, not pointer
*/
const QgsFields* fields() const;

/** Insert a value into attribute. Returns false if attribute name could not be converted to index.
* Field map must be associated to make this work.
*
* Field map must be associated using @link setFields @endlink before this method can be used.
* @param name The name of the field to set
* @param value The value to set
*
* @return false if attribute name could not be converted to index (C++ only)
*
* @note For Python: raises a KeyError exception instead of returning false
* @see setFields
*/
void setAttribute( const QString& name, QVariant value /GetWrapper/ );
%MethodCode
Expand All @@ -405,15 +448,12 @@ class QgsFeature
}
}
%End
/** Remove an attribute value.
* Returns false if attribute name could not be converted to index.
* Field map must be associated to make this work.
*
/** Removes an attribute value by field name. Field map must be associated using @link setFields @endlink
* before this method can be used.
* @param name The name of the field to delete
*
* @return false if attribute name could not be converted to index (C++ only)
*
* @note For Python: raises a KeyError exception instead of returning false
* @see setFields
*/
bool deleteAttribute( const QString& name );
%MethodCode
Expand All @@ -428,15 +468,12 @@ class QgsFeature
sipCpp->deleteAttribute( fieldIdx );
}
%End
/** Lookup attribute value from attribute name.
* Returns invalid variant if attribute name could not be converted to index (C++ only)
* Field map must be associated to make this work.
*
/** Lookup attribute value from attribute name. Field map must be associated using @link setFields @endlink
* before this method can be used.
* @param name The name of the attribute to get
*
* @return The value of the attribute (C++: Invalid variant if no such name exists )
*
* @note For Python: raises a KeyError exception if field is not found
* @see setFields
*/
SIP_PYOBJECT attribute( const QString& name ) const;
%MethodCode
Expand All @@ -452,8 +489,11 @@ class QgsFeature
sipRes = sipConvertFromNewType( v, sipType_QVariant, Py_None );
}
%End
/** Utility method to get attribute index from name. Returns -1 if field does not exist or field map is not associated.
* Field map must be associated to make this work.
/** Utility method to get attribute index from name. Field map must be associated using @link setFields @endlink
* before this method can be used.
* @param fieldName name of field to get attribute index of
* @returns -1 if field does not exist or field map is not associated.
* @see setFields
*/
int fieldNameIndex( const QString& fieldName ) const;

Expand Down
1 change: 1 addition & 0 deletions src/core/CMakeLists.txt
View file
Expand Up @@ -503,6 +503,7 @@ SET(QGIS_CORE_HDRS
qgsexpression.h
qgsexpressionfieldbuffer.h
qgsfeature.h
qgsfeature_p.h
qgsfeatureiterator.h
qgsfeaturerequest.h
qgsfeaturestore.h
Expand Down

0 comments on commit 267d952

Please sign in to comment.