[FEATURE] Vector layer save as: offer file/layer overwriting, new layer creation, feature and field appending

When saving a vector layer into an existing file, depending on the capabilities
of the output driver, the user can now decide whether:
- to overwrite the whole file
- to overwrite only the target layer (layer name is now configurable)
- to append features to the existing target layer
- to append features, add new fields if there are any.

All above is available for drivers like GPKG, SpatiaLite, FileGDB, ...
For drivers like Shapefile, MapInfo .tab, feature append is also available.

Backported from master 688d1a5

Author: rouault

python/core/qgsvectorfilewriter.sip

@@ -132,6 +132,43 @@ class QgsVectorFileWriter
         virtual QVariant convert( int fieldIdxInLayer, const QVariant& value );
     };
 
+    /** Edition capability flags
+      * @note Added in QGIS 3.0 */
+    enum EditionCapability
+    {
+        /** Flag to indicate that a new layer can be added to the dataset */
+        CanAddNewLayer,
+
+        /** Flag to indicate that new features can be added to an existing layer */
+        CanAppendToExistingLayer ,
+
+        /** Flag to indicate that new fields can be added to an existing layer. Imply CanAppendToExistingLayer */
+        CanAddNewFieldsToExistingLayer,
+
+        /** Flag to indicate that an existing layer can be deleted */
+        CanDeleteLayer
+    };
+
+    typedef QFlags<QgsVectorFileWriter::EditionCapability> EditionCapabilities;
+
+    /** Enumeration to describe how to handle existing files
+        @note Added in QGIS 3.0
+     */
+    enum ActionOnExistingFile
+    {
+        /** Create or overwrite file */
+        CreateOrOverwriteFile,
+
+        /** Create or overwrite layer */
+        CreateOrOverwriteLayer,
+
+        /** Append features to existing layer, but do not create new fields */
+        AppendToLayerNoNewFields,
+
+        /** Append features to existing layer, and create new fields if needed */
+        AppendToLayerAddFields
+    };
+
     /** Write contents of vector layer to an (OGR supported) vector formt
      * @param layer layer to write
      * @param fileName file name to write to
@@ -219,6 +256,88 @@ class QgsVectorFileWriter
                                             FieldValueConverter* fieldValueConverter = nullptr
                                           );
 
+
+    /**
+     * Options to pass to writeAsVectorFormat()
+     * @note Added in QGIS 3.0
+     */
+    class SaveVectorOptions
+    {
+      public:
+        /** Constructor */
+        SaveVectorOptions();
+
+        /** Destructor */
+        virtual ~SaveVectorOptions();
+
+        /** OGR driver to use */
+        QString driverName;
+
+        /** Layer name. If let empty, it will be derived from the filename */
+        QString layerName;
+
+        /** Action on existing file  */
+        QgsVectorFileWriter::ActionOnExistingFile actionOnExistingFile;
+
+        /** Encoding to use */
+        QString fileEncoding;
+
+        /** Transform to reproject exported geometries with, or invalid transform
+         * for no transformation */
+        const QgsCoordinateTransform* ct;
+
+        /** Write only selected features of layer */
+        bool onlySelectedFeatures;
+
+        /** List of OGR data source creation options */
+        QStringList datasourceOptions;
+
+        /** List of OGR layer creation options */
+        QStringList layerOptions;
+
+        /** Only write geometries */
+        bool skipAttributeCreation;
+
+        /** Attributes to export (empty means all unless skipAttributeCreation is set) */
+        QgsAttributeList attributes;
+
+        /** Symbology to export */
+        QgsVectorFileWriter::SymbologyExport symbologyExport;
+
+        /** Scale of symbology */
+        double symbologyScale;
+
+        /** If not empty, only features intersecting the extent will be saved */
+        QgsRectangle filterExtent;
+
+        /** Set to a valid geometry type to override the default geometry type for the layer. This parameter
+         * allows for conversion of geometryless tables to null geometries, etc */
+        QgsWKBTypes::Type overrideGeometryType;
+
+        /** Set to true to force creation of multi* geometries */
+        bool forceMulti;
+
+        /** Set to true to include z dimension in output. This option is only valid if overrideGeometryType is set */
+        bool includeZ;
+
+        /** Field value converter */
+        QgsVectorFileWriter::FieldValueConverter* fieldValueConverter;
+    };
+
+    /** Writes a layer out to a vector file.
+     * @param layer source layer to write
+     * @param fileName file name to write to
+     * @param options options.
+     * @param newFilename QString pointer which will contain the new file name created (in case it is different to fileName).
+     * @param errorMessage pointer to buffer fo error message
+     * @note added in 3.0
+     */
+    static WriterError writeAsVectorFormat( QgsVectorLayer* layer,
+                                            const QString& fileName,
+                                            const SaveVectorOptions& options,
+                                            QString *newFilename = nullptr,
+                                            QString *errorMessage = nullptr );
+
     /** Create a new vector file writer */
     QgsVectorFileWriter( const QString& vectorFileName,
                          const QString& fileEncoding,
@@ -292,6 +411,28 @@ class QgsVectorFileWriter
 
     static bool driverMetadata( const QString& driverName, MetaData& driverMetadata );
 
+    /**
+     * Return edition capabilites for an existing dataset name.
+     * @note added in QGIS 3.0
+     */
+    static EditionCapabilities editionCapabilities( const QString& datasetName );
+
+    /**
+     * Returns whether the target layer already exists.
+     * @note added in QGIS 3.0
+     */
+    static bool targetLayerExists( const QString& datasetName,
+                                   const QString& layerName );
+
+    /**
+     * Returns whether there are among the attributes specified some that do not exist yet in the layer
+     * @note added in QGIS 3.0
+     */
+    static bool areThereNewFieldsToCreate( const QString& datasetName,
+                                           const QString& layerName,
+                                           QgsVectorLayer* layer,
+                                           const QgsAttributeList& attributes );
+
   protected:
     //! @note not available in python bindings
     // OGRGeometryH createEmptyGeometry( QGis::WkbType wkbType );
@@ -300,3 +441,5 @@ class QgsVectorFileWriter
 
     QgsVectorFileWriter( const QgsVectorFileWriter& rh );
 };
+
+QFlags<QgsVectorFileWriter::EditionCapability> operator|(QgsVectorFileWriter::EditionCapability f1, QFlags<QgsVectorFileWriter::EditionCapability> f2);