Add a flag argument to QgsFeatureSink::addFeatures

Flags can be used to control how features are added to the sink.

For now, there's only a single flag available - FastInsert.
When FastInsert is set, faster inserts will be use at the cost
of updating the passed features to reflect changes made at the
provider.

This includes skipping the update of the passed feature IDs
to match the resulting feature IDs for the feature within
the data provider.

Individual sink subclasses may or may not choose to respect
this flag, depending on whether or not skipping this update
represents a significant speed boost for the operation.

QgsVectorLayer always ignores the flag - feature ids are
required for the featureAdded signal to be correctly emitted,
and it's expected that performance critical applications will
add features directly to a data provider instead of
via QgsVectorLayer's edit buffer.

Author: nyalldawson

python/core/qgsfeaturesink.sip

@@ -22,33 +22,44 @@ class QgsFeatureSink
 %End
   public:
 
+    enum Flag
+    {
+
+      FastInsert,
+    };
+    typedef QFlags<QgsFeatureSink::Flag> Flags;
+
+
     virtual ~QgsFeatureSink();
 
-    virtual bool addFeature( QgsFeature &feature );
+    virtual bool addFeature( QgsFeature &feature, QgsFeatureSink::Flags flags = 0 );
 %Docstring
- Adds a single ``feature`` to the sink.
+ Adds a single ``feature`` to the sink. Feature addition behavior is controlled by the specified ``flags``.
 .. seealso:: addFeatures()
  :return: true in case of success and false in case of failure
  :rtype: bool
 %End
 
-    virtual bool addFeatures( QgsFeatureList &features ) = 0;
+    virtual bool addFeatures( QgsFeatureList &features, QgsFeatureSink::Flags flags = 0 ) = 0;
 %Docstring
- Adds a list of ``features`` to the sink.
+ Adds a list of ``features`` to the sink. Feature addition behavior is controlled by the specified ``flags``.
 .. seealso:: addFeature()
  :return: true in case of success and false in case of failure
  :rtype: bool
 %End
 
-    virtual bool addFeatures( QgsFeatureIterator &iterator );
+    virtual bool addFeatures( QgsFeatureIterator &iterator, QgsFeatureSink::Flags flags = 0 );
 %Docstring
- Adds all features from the specified ``iterator`` to the sink.
+ Adds all features from the specified ``iterator`` to the sink. Feature addition behavior is controlled by the specified ``flags``.
  :return: true if all features were added successfully, or false if any feature could not be added
  :rtype: bool
 %End
 
 };
 
+QFlags<QgsFeatureSink::Flag> operator|(QgsFeatureSink::Flag f1, QFlags<QgsFeatureSink::Flag> f2);
+
+
 
 class QgsProxyFeatureSink : QgsFeatureSink
 {
@@ -73,9 +84,9 @@ class QgsProxyFeatureSink : QgsFeatureSink
 %Docstring
  Constructs a new QgsProxyFeatureSink which forwards features onto a destination ``sink``.
 %End
-    virtual bool addFeature( QgsFeature &feature );
-    virtual bool addFeatures( QgsFeatureList &features );
-    virtual bool addFeatures( QgsFeatureIterator &iterator );
+    virtual bool addFeature( QgsFeature &feature, QgsFeatureSink::Flags flags = 0 );
+    virtual bool addFeatures( QgsFeatureList &features, QgsFeatureSink::Flags flags = 0 );
+    virtual bool addFeatures( QgsFeatureIterator &iterator, QgsFeatureSink::Flags flags = 0 );
 
     QgsFeatureSink *destinationSink();
 %Docstring

python/core/qgsfeaturestore.sip

@@ -53,9 +53,9 @@ Constructor
 .. seealso:: crs()
 %End
 
-    virtual bool addFeature( QgsFeature &feature );
+    virtual bool addFeature( QgsFeature &feature, QgsFeatureSink::Flags flags = 0 );
 
-    virtual bool addFeatures( QgsFeatureList &features );
+    virtual bool addFeatures( QgsFeatureList &features, QgsFeatureSink::Flags flags = 0 );
 
 
     int count() const;

python/core/qgsvectordataprovider.sip

@@ -197,7 +197,7 @@ Bitmask of all provider's editing capabilities
  \param enumList reference to the list to fill
 %End
 
-    virtual bool addFeatures( QgsFeatureList &flist /In,Out/ );
+    virtual bool addFeatures( QgsFeatureList &flist /In,Out/, QgsFeatureSink::Flags flags = 0 );
 
     virtual bool deleteFeatures( const QgsFeatureIds &id );
 %Docstring

python/core/qgsvectorfilewriter.sip

@@ -522,9 +522,9 @@ Retrieves error message
  :rtype: str
 %End
 
-    virtual bool addFeature( QgsFeature &feature );
+    virtual bool addFeature( QgsFeature &feature, QgsFeatureSink::Flags flags = 0 );
 
-    virtual bool addFeatures( QgsFeatureList &features );
+    virtual bool addFeatures( QgsFeatureList &features, QgsFeatureSink::Flags flags = 0 );
 
 
     bool addFeature( QgsFeature &feature, QgsFeatureRenderer *renderer, QgsUnitTypes::DistanceUnit outputUnit = QgsUnitTypes::DistanceMeters );

python/core/qgsvectorlayer.sip

@@ -928,7 +928,7 @@ Return the provider type for this layer
  :rtype: QgsFeatureIterator
 %End
 
-    virtual bool addFeature( QgsFeature &feature );
+    virtual bool addFeature( QgsFeature &feature, QgsFeatureSink::Flags flags = 0 );
 
 
     bool updateFeature( QgsFeature &f );
@@ -1281,7 +1281,7 @@ Delete an attribute field (but does not commit it)
  :rtype: bool
 %End
 
-    virtual bool addFeatures( QgsFeatureList &features );
+    virtual bool addFeatures( QgsFeatureList &features, QgsFeatureSink::Flags flags = 0 );
 
 
     bool deleteFeature( QgsFeatureId fid );

python/core/qgsvectorlayerexporter.sip

@@ -114,9 +114,9 @@ class QgsVectorLayerExporter : QgsFeatureSink
  :rtype: int
 %End
 
-    virtual bool addFeatures( QgsFeatureList &features );
+    virtual bool addFeatures( QgsFeatureList &features, QgsFeatureSink::Flags flags = 0 );
 
-    virtual bool addFeature( QgsFeature &feature );
+    virtual bool addFeature( QgsFeature &feature, QgsFeatureSink::Flags flags = 0 );
 
 
     ~QgsVectorLayerExporter();

src/core/providers/memory/qgsmemoryprovider.cpp

@@ -323,7 +323,7 @@ QgsCoordinateReferenceSystem QgsMemoryProvider::crs() const
 }
 
 
-bool QgsMemoryProvider::addFeatures( QgsFeatureList &flist )
+bool QgsMemoryProvider::addFeatures( QgsFeatureList &flist, Flags )
 {
   // whether or not to update the layer extent on the fly as we add features
   bool updateExtent = mFeatures.isEmpty() || !mExtent.isEmpty();

src/core/providers/memory/qgsmemoryprovider.h

@@ -50,7 +50,7 @@ class QgsMemoryProvider : public QgsVectorDataProvider
     virtual QgsWkbTypes::Type wkbType() const override;
     virtual long featureCount() const override;
     virtual QgsFields fields() const override;
-    virtual bool addFeatures( QgsFeatureList &flist ) override;
+    virtual bool addFeatures( QgsFeatureList &flist, QgsFeatureSink::Flags flags = 0 ) override;
     virtual bool deleteFeatures( const QgsFeatureIds &id ) override;
     virtual bool addAttributes( const QList<QgsField> &attributes ) override;
     virtual bool renameAttributes( const QgsFieldNameMap &renamedAttributes ) override;

src/core/qgsfeaturesink.cpp

@@ -17,24 +17,27 @@
 
 #include "qgsfeaturestore.h"
 
-bool QgsFeatureSink::addFeature( QgsFeature &feature )
+bool QgsFeatureSink::addFeature( QgsFeature &feature, QgsFeatureSink::Flags flags )
 {
   QgsFeatureList features;
   features << feature;
-  bool result = addFeatures( features );
+  bool result = addFeatures( features, flags );
 
-  // need to update the passed feature reference to the updated copy from the features list
-  feature = features.at( 0 );
+  if ( !( flags & FastInsert ) )
+  {
+    // need to update the passed feature reference to the updated copy from the features list
+    feature = features.at( 0 );
+  }
   return result;
 }
 
-bool QgsFeatureSink::addFeatures( QgsFeatureIterator &iterator )
+bool QgsFeatureSink::addFeatures( QgsFeatureIterator &iterator, QgsFeatureSink::Flags flags )
 {
   QgsFeature f;
   bool result = true;
   while ( iterator.nextFeature( f ) )
   {
-    result = result && addFeature( f );
+    result = result && addFeature( f, flags );
   }
   return result;
 }

src/core/qgsfeaturesink.h

@@ -34,30 +34,47 @@ class CORE_EXPORT QgsFeatureSink
 {
   public:
 
+    //! Flags controlling how features are added to a sink.
+    enum Flag
+    {
+
+      /**
+        * Use faster inserts, at the cost of updating the passed features to reflect changes made at the provider.
+        * This includes skipping the update of the passed feature IDs to match the resulting feature IDs for the
+        * feature within the data provider.
+        * Individual sink subclasses may or may not choose to respect this flag, depending on whether or not
+        * skipping this update represents a significant speed boost for the operation.
+        */
+      FastInsert = 1 << 1,
+    };
+    Q_DECLARE_FLAGS( Flags, Flag )
+
     virtual ~QgsFeatureSink() = default;
 
     /**
-     * Adds a single \a feature to the sink.
+     * Adds a single \a feature to the sink. Feature addition behavior is controlled by the specified \a flags.
      * \see addFeatures()
      * \returns true in case of success and false in case of failure
      */
-    virtual bool addFeature( QgsFeature &feature );
+    virtual bool addFeature( QgsFeature &feature, QgsFeatureSink::Flags flags = 0 );
 
     /**
-     * Adds a list of \a features to the sink.
+     * Adds a list of \a features to the sink. Feature addition behavior is controlled by the specified \a flags.
      * \see addFeature()
      * \returns true in case of success and false in case of failure
      */
-    virtual bool addFeatures( QgsFeatureList &features ) = 0;
+    virtual bool addFeatures( QgsFeatureList &features, QgsFeatureSink::Flags flags = 0 ) = 0;
 
     /**
-     * Adds all features from the specified \a iterator to the sink.
+     * Adds all features from the specified \a iterator to the sink. Feature addition behavior is controlled by the specified \a flags.
      * \returns true if all features were added successfully, or false if any feature could not be added
      */
-    virtual bool addFeatures( QgsFeatureIterator &iterator );
+    virtual bool addFeatures( QgsFeatureIterator &iterator, QgsFeatureSink::Flags flags = 0 );
 
 };
 
+Q_DECLARE_OPERATORS_FOR_FLAGS( QgsFeatureSink::Flags )
+
 
 /**
  * \class QgsProxyFeatureSink
@@ -80,9 +97,9 @@ class CORE_EXPORT QgsProxyFeatureSink : public QgsFeatureSink
      * Constructs a new QgsProxyFeatureSink which forwards features onto a destination \a sink.
      */
     QgsProxyFeatureSink( QgsFeatureSink *sink );
-    bool addFeature( QgsFeature &feature ) override { return mSink->addFeature( feature ); }
-    bool addFeatures( QgsFeatureList &features ) override { return mSink->addFeatures( features ); }
-    bool addFeatures( QgsFeatureIterator &iterator ) override { return mSink->addFeatures( iterator ); }
+    bool addFeature( QgsFeature &feature, QgsFeatureSink::Flags flags = 0 ) override { return mSink->addFeature( feature, flags ); }
+    bool addFeatures( QgsFeatureList &features, QgsFeatureSink::Flags flags = 0 ) override { return mSink->addFeatures( features, flags ); }
+    bool addFeatures( QgsFeatureIterator &iterator, QgsFeatureSink::Flags flags = 0 ) override { return mSink->addFeatures( iterator, flags ); }
 
     /**
      * Returns the destination QgsFeatureSink which the proxy will forward features to.