Update for pull request #89: Change how setProperties() updates tags.

For file types supporting more than one tag format, setProperties() now always creates the most modern one. Deprecated tags are stripped.

taglib/ape/apefile.cpp

@@ -131,12 +131,9 @@ void APE::File::removeUnsupportedProperties(const StringList &properties)
 
 PropertyMap APE::File::setProperties(const PropertyMap &properties)
 {
-  PropertyMap result;
   if(d->hasID3v1)
-    result = d->tag.access<ID3v1::Tag>(ApeID3v1Index, false)->setProperties(properties);
-  if(d->hasAPE || !d->hasID3v1)
-    result = d->tag.access<APE::Tag>(ApeAPEIndex, true)->setProperties(properties);
-  return result;
+    strip(ID3v1);
+  return d->tag.access<APE::Tag>(ApeAPEIndex, true)->setProperties(properties);
 }
 
 APE::Properties *APE::File::audioProperties() const

taglib/ape/apefile.h

@@ -128,8 +128,9 @@ namespace TagLib {
 
       /*!
        * Implements the unified property interface -- import function.
-       * As for the export, only one tag is taken into account. If the file
-       * has no tag at all, APE will be created.
+       * Creates an APEv2 tag if necessary. A pontentially existing ID3v1
+       * tag is considered deprecated and will be removed, invalidating all
+       * pointers to that tag.
        */
       PropertyMap setProperties(const PropertyMap &);
 

taglib/flac/flacfile.cpp

@@ -168,14 +168,11 @@ void FLAC::File::removeUnsupportedProperties(const StringList &unsupported)
 
 PropertyMap FLAC::File::setProperties(const PropertyMap &properties)
 {
-  PropertyMap result;
   if(d->hasID3v1)
-      result = d->tag.access<ID3v1::Tag>(FlacID3v1Index, false)->setProperties(properties);
+      d->tag.access<ID3v1::Tag>(FlacID3v1Index, false)->setProperties(properties);
   if(d->hasID3v2)
-      result = d->tag.access<ID3v2::Tag>(FlacID3v2Index, false)->setProperties(properties);
-  if(d->hasXiphComment || !(d->hasID3v1 || d->hasID3v2))
-    result = d->tag.access<Ogg::XiphComment>(FlacXiphIndex, true)->setProperties(properties);
-  return result;
+      d->tag.access<ID3v2::Tag>(FlacID3v2Index, false)->setProperties(properties);
+  return d->tag.access<Ogg::XiphComment>(FlacXiphIndex, true)->setProperties(properties);
 }
 
 FLAC::Properties *FLAC::File::audioProperties() const

taglib/flac/flacfile.h

@@ -133,8 +133,9 @@ namespace TagLib {
 
       /*!
        * Implements the unified property interface -- import function.
-       * As with the export, only one tag is taken into account. If the file
-       * has no tag at all, a XiphComment will be created.
+       * This always creates a Xiph comment, if none exists. The return value
+       * relates to the Xiph comment only.
+       * Potential ID3v1 and ID3v2 tags will also be updated.
        */
       PropertyMap setProperties(const PropertyMap &);
 

taglib/mpc/mpcfile.cpp

@@ -135,12 +135,9 @@ void MPC::File::removeUnsupportedProperties(const StringList &properties)
 
 PropertyMap MPC::File::setProperties(const PropertyMap &properties)
 {
-  PropertyMap result;
   if(d->hasID3v1)
-    result = d->tag.access<ID3v1::Tag>(MPCID3v1Index, false)->setProperties(properties);
-  if(d->hasAPE || !d->hasID3v1)
-    result = d->tag.access<APE::Tag>(MPCAPEIndex, true)->setProperties(properties);
-  return result;
+    strip(ID3v1);
+  return d->tag.access<APE::Tag>(MPCAPEIndex, true)->setProperties(properties);
 }
 
 MPC::Properties *MPC::File::audioProperties() const

taglib/mpc/mpcfile.h

@@ -124,8 +124,8 @@ namespace TagLib {
 
       /*!
        * Implements the unified property interface -- import function.
-       * As with the export, only one tag is taken into account. If the file
-       * has no tag at all, an APE tag will be created.
+       * Affects only the APEv2 tag which will be created if necessary.
+       * If an ID3v1 tag exists, it will be stripped from the file.
        */
       PropertyMap setProperties(const PropertyMap &);
 

taglib/mpeg/mpegfile.cpp

@@ -159,14 +159,12 @@ void MPEG::File::removeUnsupportedProperties(const StringList &properties)
 
 PropertyMap MPEG::File::setProperties(const PropertyMap &properties)
 {
-  PropertyMap result;
-  if(d->hasID3v1)
-      result = d->tag.access<ID3v1::Tag>(ID3v1Index, false)->setProperties(properties);
   if(d->hasAPE)
-      result = d->tag.access<APE::Tag>(APEIndex, false)->setProperties(properties);
-  if(d->hasID3v2 || !(d->hasID3v1 || d->hasAPE))
-    result = d->tag.access<ID3v2::Tag>(ID3v2Index, true)->setProperties(properties);
-  return result;
+    strip(APE, true);
+  if(d->hasID3v1)
+    // update ID3v1 tag if it exists, but ignore the return value
+    d->tag.access<ID3v1::Tag>(ID3v1Index, false)->setProperties(properties);
+  return d->tag.access<ID3v2::Tag>(ID3v2Index, true)->setProperties(properties);
 }
 
 MPEG::Properties *MPEG::File::audioProperties() const

taglib/mpeg/mpegfile.h

@@ -133,7 +133,7 @@ namespace TagLib {
       virtual Tag *tag() const;
 
       /*!
-       * Implements the unified property interface -- export function.
+       * Implements the reading part of the unified property interface.
        * If the file contains more than one tag, only the
        * first one (in the order ID3v2, APE, ID3v1) will be converted to the
        * PropertyMap.
@@ -143,9 +143,14 @@ namespace TagLib {
       void removeUnsupportedProperties(const StringList &properties);
 
       /*!
-       * Implements the unified tag dictionary interface -- import function.
-       * As with the export, only one tag is taken into account. If the file
-       * has no tag at all, ID3v2 will be created.
+       * Implements the writing part of the unified tag dictionary interface.
+       * In order to avoid problems with deprecated tag formats, this method
+       * always creates an ID3v2 tag if necessary, and removes potential APEv2
+       * tags (also invalidating all pointers to the APE tag) which are
+       * considered bad practice in MP3 files.
+       * If an ID3v1 tag  exists, it will be updated as well, within the
+       * limitations of that format.
+       * The returned PropertyMap refers to the ID3v2 tag only.
        */
       PropertyMap setProperties(const PropertyMap &);
 

taglib/toolkit/tfile.h

@@ -80,8 +80,8 @@ namespace TagLib {
 
     /*!
      * Exports the tags of the file as dictionary mapping (human readable) tag
-     * names (Strings) to StringLists of tag values. Calls the according specialization
-     * in the File subclasses.
+     * names (uppercase Strings) to StringLists of tag values. Calls the according
+     * specialization in the File subclasses.
      * For each metadata object of the file that could not be parsed into the PropertyMap
      * format, the returend map's unsupportedData() list will contain one entry identifying
      * that object (e.g. the frame type for ID3v2 tags). Use removeUnsupportedProperties()
@@ -105,6 +105,10 @@ namespace TagLib {
      * If some value(s) could not be written imported to the specific metadata format,
      * the returned PropertyMap will contain those value(s). Otherwise it will be empty,
      * indicating that no problems occured.
+     * With file types that support several tag formats (for instance, MP3 files can have
+     * ID3v1, ID3v2, and APEv2 tags), this function will create the most appropriate one
+     * and may remove deprecated ones (mostly ID3v1). See the documentation of the 
+     * subclass implementations for detailed descriptions.
      * BIC: will become pure virtual in the future
      */
     PropertyMap setProperties(const PropertyMap &properties);

taglib/trueaudio/trueaudiofile.cpp

@@ -141,12 +141,9 @@ PropertyMap TrueAudio::File::properties() const
 
 PropertyMap TrueAudio::File::setProperties(const PropertyMap &properties)
 {
-  PropertyMap result;
   if(d->hasID3v1)
-    result = d->tag.access<ID3v1::Tag>(TrueAudioID3v1Index, false)->setProperties(properties);
-  if(d->hasID3v2 || !d->hasID3v1)
-    result =d->tag.access<ID3v2::Tag>(TrueAudioID3v2Index, true)->setProperties(properties);
-  return result;
+    d->tag.access<ID3v1::Tag>(TrueAudioID3v1Index, false)->setProperties(properties);
+  return d->tag.access<ID3v2::Tag>(TrueAudioID3v2Index, true)->setProperties(properties);
 }
 
 TrueAudio::Properties *TrueAudio::File::audioProperties() const

taglib/trueaudio/trueaudiofile.h

@@ -139,8 +139,8 @@ namespace TagLib {
 
       /*!
        * Implements the unified property interface -- import function.
-       * As with the export, only one tag is taken into account. If the file
-       * has no tag at all, ID3v2 will be created.
+       * Creates in ID3v2 tag if necessary. If an ID3v1 tag exists, it will
+       * be updated as well, within the limitations of ID3v1.
        */
       PropertyMap setProperties(const PropertyMap &);
 

taglib/wavpack/wavpackfile.cpp

@@ -119,12 +119,9 @@ PropertyMap WavPack::File::properties() const
 
 PropertyMap WavPack::File::setProperties(const PropertyMap &properties)
 {
-  PropertyMap result;
   if(d->hasID3v1)
-    result = d->tag.access<ID3v1::Tag>(WavID3v1Index, false)->setProperties(properties);
-  if(d->hasAPE || !d->hasID3v1)
-    result = d->tag.access<APE::Tag>(WavAPEIndex, true)->setProperties(properties);
-  return result;
+    strip(ID3v1);
+  return d->tag.access<APE::Tag>(WavAPEIndex, true)->setProperties(properties);
 }
 
 WavPack::Properties *WavPack::File::audioProperties() const

taglib/wavpack/wavpackfile.h

@@ -118,8 +118,8 @@ namespace TagLib {
 
       /*!
        * Implements the unified property interface -- import function.
-       * As for the export, only one tag is taken into account. If the file
-       * has no tag at all, APE will be created.
+       * Creates an APE tag if it does not exists and calls setProperties() on
+       * that. Any existing ID3v1 tag will be removed.
        */
       PropertyMap setProperties(const PropertyMap&);