@@ -233,15 +233,15 @@ pub trait TagExt: Accessor + Into<Tag> + Sized {
233233 fn clear ( & mut self ) ;
234234}
235235
236- /// Split and rejoin tags.
236+ /// Split and merge tags.
237237///
238238/// Useful and required for implementing lossless read/modify/write round trips.
239239///
240240/// # Example
241241///
242242/// ```no_run
243243/// use lofty::mpeg::MPEGFile;
244- /// use lofty::{AudioFile, ItemKey, SplitAndRejoinTag as _};
244+ /// use lofty::{AudioFile, ItemKey, SplitAndMergeTag as _};
245245///
246246/// // Read the tag from a file
247247/// # 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 {
264264/// tag.remove_key(&ItemKey::Composer);
265265///
266266/// // ID3v2 <- [`lofty::Tag`]
267- /// id3v2.rejoin_tag (tag);
267+ /// id3v2.merge_tag (tag);
268268///
269269/// // Write the changes back into the file
270270/// mpeg_file.save_to(&mut file)?;
271271///
272272/// # Ok::<(), lofty::LoftyError>(())
273273/// ```
274- pub trait SplitAndRejoinTag {
274+ pub trait SplitAndMergeTag {
275275 /// Extract and split generic contents into a [`Tag`].
276276 ///
277277 /// Leaves the remainder that cannot be represented in the
278278 /// resulting tag in `self`. This is useful if the modified [`Tag`]
279- /// is rejoined later using [`SplitAndRejoinTag::rejoin_tag `].
279+ /// is merged later using [`SplitAndMergeTag::merge_tag `].
280280 // NOTE: Using the "typestate pattern" (http://cliffle.com/blog/rust-typestate/)
281281 // to represent the intermediate state turned out as less flexible
282282 // and useful than expected.
@@ -285,11 +285,15 @@ pub trait SplitAndRejoinTag {
285285 /// Rejoin a [`Tag`].
286286 ///
287287 /// Rejoin a tag that has previously been obtained with
288- /// [`SplitAndRejoinTag ::split_tag`].
288+ /// [`SplitAndMergeTag ::split_tag`].
289289 ///
290290 /// Restores the original representation merged with the contents of
291291 /// `tag` for further processing, e.g. writing back into a file.
292- fn rejoin_tag ( & mut self , tag : Tag ) ;
292+ ///
293+ /// This method must only be called once and after [`Self::split_tag`]!
294+ /// Otherwise the behavior is undefined and may result in redundancies
295+ /// or inconsistencies.
296+ fn merge_tag ( & mut self , tag : Tag ) ;
293297}
294298
295299// TODO: https://github.com/rust-lang/rust/issues/59359
0 commit comments