Renaming: rejoin -> merge

src/ape/tag/mod.rs

@@ -6,7 +6,7 @@ use crate::ape::tag::item::{ApeItem, ApeItemRef};
 use crate::error::{LoftyError, Result};
 use crate::tag::item::{ItemKey, ItemValue, TagItem};
 use crate::tag::{Tag, TagType};
-use crate::traits::{Accessor, SplitAndRejoinTag, TagExt};
+use crate::traits::{Accessor, SplitAndMergeTag, TagExt};
 
 use std::borrow::Cow;
 use std::convert::TryInto;
@@ -289,7 +289,7 @@ impl TagExt for ApeTag {
 	}
 }
 
-impl SplitAndRejoinTag for ApeTag {
+impl SplitAndMergeTag for ApeTag {
 	fn split_tag(&mut self) -> Tag {
 		fn split_pair(
 			content: &str,
@@ -349,7 +349,7 @@ impl SplitAndRejoinTag for ApeTag {
 		tag
 	}
 
-	fn rejoin_tag(&mut self, tag: Tag) {
+	fn merge_tag(&mut self, tag: Tag) {
 		for item in tag.items {
 			if let Ok(ape_item) = item.try_into() {
 				self.insert(ape_item)
@@ -377,7 +377,7 @@ impl From<ApeTag> for Tag {
 impl From<Tag> for ApeTag {
 	fn from(input: Tag) -> Self {
 		let mut ape_tag = Self::default();
-		ape_tag.rejoin_tag(input);
+		ape_tag.merge_tag(input);
 		ape_tag
 	}
 }

src/id3/v1/tag.rs

@@ -2,7 +2,7 @@ use crate::error::{LoftyError, Result};
 use crate::id3::v1::constants::GENRES;
 use crate::tag::item::{ItemKey, ItemValue, TagItem};
 use crate::tag::{Tag, TagType};
-use crate::traits::{Accessor, SplitAndRejoinTag, TagExt};
+use crate::traits::{Accessor, SplitAndMergeTag, TagExt};
 
 use std::borrow::Cow;
 use std::fs::{File, OpenOptions};
@@ -238,7 +238,7 @@ impl TagExt for ID3v1Tag {
 	}
 }
 
-impl SplitAndRejoinTag for ID3v1Tag {
+impl SplitAndMergeTag for ID3v1Tag {
 	fn split_tag(&mut self) -> Tag {
 		let mut tag = Tag::new(TagType::ID3v1);
 
@@ -272,7 +272,7 @@ impl SplitAndRejoinTag for ID3v1Tag {
 		tag
 	}
 
-	fn rejoin_tag(&mut self, tag: Tag) {
+	fn merge_tag(&mut self, tag: Tag) {
 		*self = tag.into();
 	}
 }

src/id3/v2/tag.rs

@@ -9,7 +9,7 @@ use crate::id3::v2::items::language_frame::LanguageFrame;
 use crate::picture::{Picture, PictureType, TOMBSTONE_PICTURE};
 use crate::tag::item::{ItemKey, ItemValue, TagItem};
 use crate::tag::{Tag, TagType};
-use crate::traits::{Accessor, SplitAndRejoinTag, TagExt};
+use crate::traits::{Accessor, SplitAndMergeTag, TagExt};
 use crate::util::text::TextEncoding;
 
 use std::borrow::Cow;
@@ -533,7 +533,7 @@ impl TagExt for ID3v2Tag {
 	}
 }
 
-impl SplitAndRejoinTag for ID3v2Tag {
+impl SplitAndMergeTag for ID3v2Tag {
 	fn split_tag(&mut self) -> Tag {
 		fn split_pair(
 			content: &str,
@@ -693,7 +693,7 @@ impl SplitAndRejoinTag for ID3v2Tag {
 		tag
 	}
 
-	fn rejoin_tag(&mut self, mut tag: Tag) {
+	fn merge_tag(&mut self, mut tag: Tag) {
 		fn join_items(tag: &mut Tag, key: &ItemKey) -> String {
 			let mut iter = tag.take_strings(key);
 
@@ -748,7 +748,7 @@ impl From<ID3v2Tag> for Tag {
 impl From<Tag> for ID3v2Tag {
 	fn from(input: Tag) -> Self {
 		let mut id3v2_tag = ID3v2Tag::default();
-		id3v2_tag.rejoin_tag(input);
+		id3v2_tag.merge_tag(input);
 		id3v2_tag
 	}
 }

src/iff/aiff/tag.rs

@@ -3,7 +3,7 @@ use crate::iff::chunk::Chunks;
 use crate::macros::err;
 use crate::tag::item::{ItemKey, ItemValue, TagItem};
 use crate::tag::{Tag, TagType};
-use crate::traits::{Accessor, SplitAndRejoinTag, TagExt};
+use crate::traits::{Accessor, SplitAndMergeTag, TagExt};
 
 use std::borrow::Cow;
 use std::convert::TryFrom;
@@ -216,12 +216,12 @@ impl TagExt for AIFFTextChunks {
 	}
 }
 
-impl SplitAndRejoinTag for AIFFTextChunks {
+impl SplitAndMergeTag for AIFFTextChunks {
 	fn split_tag(&mut self) -> Tag {
 		std::mem::take(self).into()
 	}
 
-	fn rejoin_tag(&mut self, tag: Tag) {
+	fn merge_tag(&mut self, tag: Tag) {
 		*self = tag.into();
 	}
 }

src/iff/wav/tag/mod.rs

@@ -4,7 +4,7 @@ mod write;
 use crate::error::{LoftyError, Result};
 use crate::tag::item::{ItemKey, ItemValue, TagItem};
 use crate::tag::{Tag, TagType};
-use crate::traits::{Accessor, SplitAndRejoinTag, TagExt};
+use crate::traits::{Accessor, SplitAndMergeTag, TagExt};
 
 use std::borrow::Cow;
 use std::fs::{File, OpenOptions};
@@ -211,12 +211,12 @@ impl TagExt for RIFFInfoList {
 	}
 }
 
-impl SplitAndRejoinTag for RIFFInfoList {
+impl SplitAndMergeTag for RIFFInfoList {
 	fn split_tag(&mut self) -> Tag {
 		std::mem::take(self).into()
 	}
 
-	fn rejoin_tag(&mut self, tag: Tag) {
+	fn merge_tag(&mut self, tag: Tag) {
 		*self = tag.into();
 	}
 }

src/lib.rs

@@ -178,7 +178,7 @@ pub use crate::tag::{Tag, TagType};
 pub use tag::item::{ItemKey, ItemValue, TagItem};
 pub use util::text::TextEncoding;
 
-pub use crate::traits::{Accessor, SplitAndRejoinTag, TagExt};
+pub use crate::traits::{Accessor, SplitAndMergeTag, TagExt};
 
 pub use picture::PictureInformation;
 

src/mp4/ilst/mod.rs

@@ -10,7 +10,7 @@ use crate::mp4::ilst::atom::AtomDataStorage;
 use crate::picture::{Picture, PictureType, TOMBSTONE_PICTURE};
 use crate::tag::item::{ItemKey, ItemValue, TagItem};
 use crate::tag::{Tag, TagType};
-use crate::traits::{Accessor, SplitAndRejoinTag, TagExt};
+use crate::traits::{Accessor, SplitAndMergeTag, TagExt};
 use atom::{AdvisoryRating, Atom, AtomData};
 
 use std::borrow::Cow;
@@ -377,7 +377,7 @@ impl TagExt for Ilst {
 	}
 }
 
-impl SplitAndRejoinTag for Ilst {
+impl SplitAndMergeTag for Ilst {
 	fn split_tag(&mut self) -> Tag {
 		let mut tag = Tag::new(TagType::MP4ilst);
 
@@ -446,7 +446,7 @@ impl SplitAndRejoinTag for Ilst {
 		tag
 	}
 
-	fn rejoin_tag(&mut self, tag: Tag) {
+	fn merge_tag(&mut self, tag: Tag) {
 		fn convert_to_uint(space: &mut Option<u16>, cont: &str) {
 			if let Ok(num) = cont.parse::<u16>() {
 				*space = Some(num);
@@ -538,7 +538,7 @@ impl From<Ilst> for Tag {
 impl From<Tag> for Ilst {
 	fn from(input: Tag) -> Self {
 		let mut ilst = Self::default();
-		ilst.rejoin_tag(input);
+		ilst.merge_tag(input);
 		ilst
 	}
 }

src/ogg/tag.rs

@@ -7,7 +7,7 @@ use crate::picture::{Picture, PictureInformation};
 use crate::probe::Probe;
 use crate::tag::item::{ItemKey, ItemValue, TagItem};
 use crate::tag::{Tag, TagType};
-use crate::traits::{Accessor, SplitAndRejoinTag, TagExt};
+use crate::traits::{Accessor, SplitAndMergeTag, TagExt};
 
 use std::borrow::Cow;
 use std::fs::{File, OpenOptions};
@@ -328,7 +328,7 @@ impl TagExt for VorbisComments {
 	}
 }
 
-impl SplitAndRejoinTag for VorbisComments {
+impl SplitAndMergeTag for VorbisComments {
 	fn split_tag(&mut self) -> Tag {
 		let mut tag = Tag::new(TagType::VorbisComments);
 
@@ -359,7 +359,7 @@ impl SplitAndRejoinTag for VorbisComments {
 		tag
 	}
 
-	fn rejoin_tag(&mut self, mut tag: Tag) {
+	fn merge_tag(&mut self, mut tag: Tag) {
 		if let Some(TagItem {
 			item_value: ItemValue::Text(val),
 			..
@@ -403,7 +403,7 @@ impl From<VorbisComments> for Tag {
 impl From<Tag> for VorbisComments {
 	fn from(input: Tag) -> Self {
 		let mut vorbis_comments = Self::default();
-		vorbis_comments.rejoin_tag(input);
+		vorbis_comments.merge_tag(input);
 		vorbis_comments
 	}
 }

src/tag/mod.rs

@@ -6,7 +6,7 @@ use crate::file::FileType;
 use crate::macros::err;
 use crate::picture::{Picture, PictureType};
 use crate::probe::Probe;
-use crate::traits::{Accessor, SplitAndRejoinTag, TagExt};
+use crate::traits::{Accessor, SplitAndMergeTag, TagExt};
 use item::{ItemKey, ItemValue, TagItem};
 
 use std::borrow::Cow;
@@ -583,12 +583,12 @@ impl TagExt for Tag {
 	}
 }
 
-impl SplitAndRejoinTag for Tag {
+impl SplitAndMergeTag for Tag {
 	fn split_tag(&mut self) -> Self {
 		std::mem::replace(self, Self::new(self.tag_type))
 	}
 
-	fn rejoin_tag(&mut self, tag: Self) {
+	fn merge_tag(&mut self, tag: Self) {
 		*self = tag;
 	}
 }

src/traits.rs

@@ -233,7 +233,7 @@ pub trait TagExt: Accessor + Into<Tag> + Sized {
 	fn clear(&mut self);
 }
 
-/// Split and rejoin tags.
+/// Split and merge tags.
 ///
 /// Useful and required for implementing lossless read/modify/write round trips.
 ///
@@ -241,7 +241,7 @@ pub trait TagExt: Accessor + Into<Tag> + Sized {
 ///
 /// ```no_run
 /// use lofty::mpeg::MPEGFile;
-/// use lofty::{AudioFile, ItemKey, SplitAndRejoinTag as _};
+/// use lofty::{AudioFile, ItemKey, SplitAndMergeTag as _};
 ///
 /// // Read the tag from a file
 /// # let mut file = std::fs::OpenOptions::new().write(true).open("/path/to/file.mp3")?;
@@ -264,19 +264,19 @@ pub trait TagExt: Accessor + Into<Tag> + Sized {
 /// tag.remove_key(&ItemKey::Composer);
 ///
 /// // ID3v2 <- [`lofty::Tag`]
-/// id3v2.rejoin_tag(tag);
+/// id3v2.merge_tag(tag);
 ///
 /// // Write the changes back into the file
 /// mpeg_file.save_to(&mut file)?;
 ///
 /// # Ok::<(), lofty::LoftyError>(())
 /// ```
-pub trait SplitAndRejoinTag {
+pub trait SplitAndMergeTag {
 	/// Extract and split generic contents into a [`Tag`].
 	///
 	/// Leaves the remainder that cannot be represented in the
 	/// resulting tag in `self`. This is useful if the modified [`Tag`]
-	/// is rejoined later using [`SplitAndRejoinTag::rejoin_tag`].
+	/// is merged later using [`SplitAndMergeTag::merge_tag`].
 	// NOTE: Using the "typestate pattern" (http://cliffle.com/blog/rust-typestate/)
 	// to represent the intermediate state turned out as less flexible
 	// and useful than expected.
@@ -285,11 +285,15 @@ pub trait SplitAndRejoinTag {
 	/// Rejoin a [`Tag`].
 	///
 	/// Rejoin a tag that has previously been obtained with
-	/// [`SplitAndRejoinTag::split_tag`].
+	/// [`SplitAndMergeTag::split_tag`].
 	///
 	/// Restores the original representation merged with the contents of
 	/// `tag` for further processing, e.g. writing back into a file.
-	fn rejoin_tag(&mut self, tag: Tag);
+	///
+	/// This method must only be called once and after [`Self::split_tag`]!
+	/// Otherwise the behavior is undefined and may result in redundancies
+	/// or inconsistencies.
+	fn merge_tag(&mut self, tag: Tag);
 }
 
 // TODO: https://github.com/rust-lang/rust/issues/59359