libFLAC++: all metadata object operator=() funcs now return *this; add Metadata::*::assign() and FLAC::Metadata::get_tags()

doc/html/changelog.html

@@ -155,6 +155,7 @@
 					<UL>
 						<LI><B>Changed:</B> Metadata object interface now maintains a trailing NULL on Vorbis comment values for convenience.</LI>
 						<LI><B>Changed:</B> Metadata object interface now validates all Vorbis comment entries on input and returns false if an entry does not conform to the Vorbis comment spec.</LI>
+						<LI><B>Changed:</B> All Metadata objects' operator=() methods now return a reference to themselves.</LI>
 						<LI><B>Added</B> methods to FLAC::Metadata::VorbisComment::Entry for setting comment values from null-terminated strings:
 							<UL>
 								<LI>Entry(const char *field)</LI>
@@ -164,6 +165,8 @@
 							</UL>
 						</LI>
 						<LI><B>Changed</B> the signature of FLAC::Metadata::VorbisComment::get_vendor_string() and FLAC::Metadata::VorbisComment::set_vendor_string() to use a UTF-8, NUL-terminated string <TT>const FLAC__byte *</TT> for the vendor string instead of <TT>FLAC::Metadata::VorbisComment::Entry</TT>.</LI>
+						<LI><B>Added</B> FLAC::Metadata::*::assign() to all Metadata objects.</LI>
+						<LI><B>Added</B> bool FLAC::Metadata::get_tags(const char *filename, VorbisComment &tags)</LI>
 					</UL>
 				</LI>
 				<LI>

include/FLAC++/metadata.h

@@ -126,11 +126,16 @@ namespace FLAC {
 
 			//@{
 			/** Assign from another object.  Always performs a deep copy. */
-			void operator=(const Prototype &);
+			Prototype &operator=(const Prototype &);
-			void operator=(const ::FLAC__StreamMetadata &);
+			Prototype &operator=(const ::FLAC__StreamMetadata &);
-			void operator=(const ::FLAC__StreamMetadata *);
+			Prototype &operator=(const ::FLAC__StreamMetadata *);
 			//@}
 
+			/** Assigns an object with copy control.  See
+			 *  Prototype(::FLAC__StreamMetadata *object, bool copy).
+			 */
+			Prototype &assign_object(::FLAC__StreamMetadata *object, bool copy);
+
 			/** Deletes the underlying ::FLAC__StreamMetadata object.
 			 */
 			virtual void clear();
@@ -278,11 +283,16 @@ namespace FLAC {
 
 			//@{
 			/** Assign from another object.  Always performs a deep copy. */
-			inline void operator=(const StreamInfo &object) { Prototype::operator=(object); }
+			inline StreamInfo &operator=(const StreamInfo &object) { Prototype::operator=(object); return *this; }
-			inline void operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); }
+			inline StreamInfo &operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); return *this; }
-			inline void operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); }
+			inline StreamInfo &operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); return *this; }
 			//@}
 
+			/** Assigns an object with copy control.  See
+			 *  Prototype::assign_object(::FLAC__StreamMetadata *object, bool copy).
+			 */
+			inline StreamInfo &assign(::FLAC__StreamMetadata *object, bool copy) { Prototype::assign_object(object, copy); return *this; }
+
 			//@{
 			/** Check for equality, performing a deep compare by following pointers. */
 			inline bool operator==(const StreamInfo &object) const { return Prototype::operator==(object); }
@@ -346,11 +356,16 @@ namespace FLAC {
 
 			//@{
 			/** Assign from another object.  Always performs a deep copy. */
-			inline void operator=(const Padding &object) { Prototype::operator=(object); }
+			inline Padding &operator=(const Padding &object) { Prototype::operator=(object); return *this; }
-			inline void operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); }
+			inline Padding &operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); return *this; }
-			inline void operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); }
+			inline Padding &operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); return *this; }
 			//@}
 
+			/** Assigns an object with copy control.  See
+			 *  Prototype::assign_object(::FLAC__StreamMetadata *object, bool copy).
+			 */
+			inline Padding &assign(::FLAC__StreamMetadata *object, bool copy) { Prototype::assign_object(object, copy); return *this; }
+
 			//@{
 			/** Check for equality, performing a deep compare by following pointers. */
 			inline bool operator==(const Padding &object) const { return Prototype::operator==(object); }
@@ -393,11 +408,16 @@ namespace FLAC {
 
 			//@{
 			/** Assign from another object.  Always performs a deep copy. */
-			inline void operator=(const Application &object) { Prototype::operator=(object); }
+			inline Application &operator=(const Application &object) { Prototype::operator=(object); return *this; }
-			inline void operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); }
+			inline Application &operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); return *this; }
-			inline void operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); }
+			inline Application &operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); return *this; }
 			//@}
 
+			/** Assigns an object with copy control.  See
+			 *  Prototype::assign_object(::FLAC__StreamMetadata *object, bool copy).
+			 */
+			inline Application &assign(::FLAC__StreamMetadata *object, bool copy) { Prototype::assign_object(object, copy); return *this; }
+
 			//@{
 			/** Check for equality, performing a deep compare by following pointers. */
 			inline bool operator==(const Application &object) const { return Prototype::operator==(object); }
@@ -446,11 +466,16 @@ namespace FLAC {
 
 			//@{
 			/** Assign from another object.  Always performs a deep copy. */
-			inline void operator=(const SeekTable &object) { Prototype::operator=(object); }
+			inline SeekTable &operator=(const SeekTable &object) { Prototype::operator=(object); return *this; }
-			inline void operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); }
+			inline SeekTable &operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); return *this; }
-			inline void operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); }
+			inline SeekTable &operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); return *this; }
 			//@}
 
+			/** Assigns an object with copy control.  See
+			 *  Prototype::assign_object(::FLAC__StreamMetadata *object, bool copy).
+			 */
+			inline SeekTable &assign(::FLAC__StreamMetadata *object, bool copy) { Prototype::assign_object(object, copy); return *this; }
+
 			//@{
 			/** Check for equality, performing a deep compare by following pointers. */
 			inline bool operator==(const SeekTable &object) const { return Prototype::operator==(object); }
@@ -527,7 +552,7 @@ namespace FLAC {
 
 				Entry(const Entry &entry);
 
-				void operator=(const Entry &entry);
+				Entry &operator=(const Entry &entry);
 
 				virtual ~Entry();
 
@@ -588,11 +613,16 @@ namespace FLAC {
 
 			//@{
 			/** Assign from another object.  Always performs a deep copy. */
-			inline void operator=(const VorbisComment &object) { Prototype::operator=(object); }
+			inline VorbisComment &operator=(const VorbisComment &object) { Prototype::operator=(object); return *this; }
-			inline void operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); }
+			inline VorbisComment &operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); return *this; }
-			inline void operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); }
+			inline VorbisComment &operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); return *this; }
 			//@}
 
+			/** Assigns an object with copy control.  See
+			 *  Prototype::assign_object(::FLAC__StreamMetadata *object, bool copy).
+			 */
+			inline VorbisComment &assign(::FLAC__StreamMetadata *object, bool copy) { Prototype::assign_object(object, copy); return *this; }
+
 			//@{
 			/** Check for equality, performing a deep compare by following pointers. */
 			inline bool operator==(const VorbisComment &object) const { return Prototype::operator==(object); }
@@ -645,7 +675,7 @@ namespace FLAC {
 				Track();
 				Track(const ::FLAC__StreamMetadata_CueSheet_Track *track);
 				Track(const Track &track);
-				void operator=(const Track &track);
+				Track &operator=(const Track &track);
 
 				virtual ~Track();
 
@@ -693,11 +723,16 @@ namespace FLAC {
 
 			//@{
 			/** Assign from another object.  Always performs a deep copy. */
-			inline void operator=(const CueSheet &object) { Prototype::operator=(object); }
+			inline CueSheet &operator=(const CueSheet &object) { Prototype::operator=(object); return *this; }
-			inline void operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); }
+			inline CueSheet &operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); return *this; }
-			inline void operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); }
+			inline CueSheet &operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); return *this; }
 			//@}
 
+			/** Assigns an object with copy control.  See
+			 *  Prototype::assign_object(::FLAC__StreamMetadata *object, bool copy).
+			 */
+			inline CueSheet &assign(::FLAC__StreamMetadata *object, bool copy) { Prototype::assign_object(object, copy); return *this; }
+
 			//@{
 			/** Check for equality, performing a deep compare by following pointers. */
 			inline bool operator==(const CueSheet &object) const { return Prototype::operator==(object); }
@@ -771,11 +806,16 @@ namespace FLAC {
 
 			//@{
 			/** Assign from another object.  Always performs a deep copy. */
-			inline void operator=(const Unknown &object) { Prototype::operator=(object); }
+			inline Unknown &operator=(const Unknown &object) { Prototype::operator=(object); return *this; }
-			inline void operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); }
+			inline Unknown &operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); return *this; }
-			inline void operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); }
+			inline Unknown &operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); return *this; }
 			//@}
 
+			/** Assigns an object with copy control.  See
+			 *  Prototype::assign_object(::FLAC__StreamMetadata *object, bool copy).
+			 */
+			inline Unknown &assign(::FLAC__StreamMetadata *object, bool copy) { Prototype::assign_object(object, copy); return *this; }
+
 			//@{
 			/** Check for equality, performing a deep compare by following pointers. */
 			inline bool operator==(const Unknown &object) const { return Prototype::operator==(object); }
@@ -817,6 +857,7 @@ namespace FLAC {
 
 	 	//! See FLAC__metadata_get_tags().
 		FLACPP_API bool get_tags(const char *filename, VorbisComment *&tags);
+		FLACPP_API bool get_tags(const char *filename, VorbisComment &tags);
 
 		/* \} */
 

src/libFLAC++/metadata.cpp

@@ -152,27 +152,39 @@ namespace FLAC {
 			object_ = 0;
 		}
 
-		void Prototype::operator=(const Prototype &object)
+		Prototype &Prototype::operator=(const Prototype &object)
 		{
 			FLAC__ASSERT(object.is_valid());
 			clear();
 			is_reference_ = false;
 			object_ = ::FLAC__metadata_object_clone(object.object_);
+			return *this;
 		}
 
-		void Prototype::operator=(const ::FLAC__StreamMetadata &object)
+		Prototype &Prototype::operator=(const ::FLAC__StreamMetadata &object)
 		{
 			clear();
 			is_reference_ = false;
 			object_ = ::FLAC__metadata_object_clone(&object);
+			return *this;
 		}
 
-		void Prototype::operator=(const ::FLAC__StreamMetadata *object)
+		Prototype &Prototype::operator=(const ::FLAC__StreamMetadata *object)
 		{
 			FLAC__ASSERT(0 != object);
 			clear();
 			is_reference_ = false;
 			object_ = ::FLAC__metadata_object_clone(object);
+			return *this;
+		}
+
+		Prototype &Prototype::assign_object(::FLAC__StreamMetadata *object, bool copy)
+		{
+			FLAC__ASSERT(0 != object);
+			clear();
+			object_ = (copy? ::FLAC__metadata_object_clone(object) : object);
+			is_reference_ = false;
+			return *this;
 		}
 
 		bool Prototype::get_is_last() const
@@ -486,11 +498,12 @@ namespace FLAC {
 			construct((const char *)entry.entry_.entry, entry.entry_.length);
 		}
 
-		void VorbisComment::Entry::operator=(const Entry &entry)
+		VorbisComment::Entry &VorbisComment::Entry::operator=(const Entry &entry)
 		{
 			FLAC__ASSERT(entry.is_valid());
 			clear();
 			construct((const char *)entry.entry_.entry, entry.entry_.length);
+			return *this;
 		}
 
 		VorbisComment::Entry::~Entry()
@@ -830,11 +843,12 @@ namespace FLAC {
 		object_(::FLAC__metadata_object_cuesheet_track_clone(track.object_))
 		{ }
 
-		void CueSheet::Track::operator=(const Track &track)
+		CueSheet::Track &CueSheet::Track::operator=(const Track &track)
 		{
 			if(0 != object_)
 				::FLAC__metadata_object_cuesheet_track_delete(object_);
 			object_ = ::FLAC__metadata_object_cuesheet_track_clone(track.object_);
+			return *this;
 		}
 
 		CueSheet::Track::~Track()
@@ -1060,6 +1074,20 @@ namespace FLAC {
 				return false;
 		}
 
+		FLACPP_API bool get_tags(const char *filename, VorbisComment &tags)
+		{
+			FLAC__ASSERT(0 != filename);
+
+			::FLAC__StreamMetadata *object;
+
+			if(::FLAC__metadata_get_tags(filename, &object)) {
+				tags.assign(object, /*copy=*/false);
+				return true;
+			}
+			else
+				return false;
+		}
+
 
 		// ============================================================
 		//