Implicit sharing for QgsFeature

Author: nyalldawson

python/core/qgsfeature.sip

@@ -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
@@ -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
@@ -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 );
@@ -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
@@ -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
@@ -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
@@ -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;
 

src/core/CMakeLists.txt

@@ -503,6 +503,7 @@ SET(QGIS_CORE_HDRS
   qgsexpression.h
   qgsexpressionfieldbuffer.h
   qgsfeature.h
+  qgsfeature_p.h
   qgsfeatureiterator.h
   qgsfeaturerequest.h
   qgsfeaturestore.h