MP4: Add Atom::{merge, into_data}

Author: Serial-ATA

src/error.rs

@@ -53,6 +53,8 @@ pub enum ErrorKind {
 
 	/// Arises when an atom contains invalid data
 	BadAtom(&'static str),
+	/// Arises when attempting to use [`Atom::merge`](crate::mp4::Atom::merge) with mismatching identifiers
+	AtomMismatch,
 
 	// Conversions for external errors
 	/// Errors that arise while parsing OGG pages
@@ -520,6 +522,10 @@ impl Display for LoftyError {
 			ErrorKind::TextDecode(message) => write!(f, "Text decoding: {message}"),
 			ErrorKind::Id3v2(ref id3v2_err) => write!(f, "{id3v2_err}"),
 			ErrorKind::BadAtom(message) => write!(f, "MP4 Atom: {message}"),
+			ErrorKind::AtomMismatch => write!(
+				f,
+				"MP4 Atom: Attempted to use `Atom::merge()` with mismatching identifiers"
+			),
 
 			// Files
 			ErrorKind::TooMuchData => write!(

src/mp4/ilst/atom.rs

@@ -1,3 +1,5 @@
+use crate::error::Result;
+use crate::macros::err;
 use crate::mp4::AtomIdent;
 use crate::picture::Picture;
 
@@ -29,6 +31,18 @@ impl Debug for AtomDataStorage {
 	}
 }
 
+impl IntoIterator for AtomDataStorage {
+	type Item = AtomData;
+	type IntoIter = std::vec::IntoIter<Self::Item>;
+
+	fn into_iter(self) -> Self::IntoIter {
+		match self {
+			AtomDataStorage::Single(s) => vec![s].into_iter(),
+			AtomDataStorage::Multiple(v) => v.into_iter(),
+		}
+	}
+}
+
 impl<'a> IntoIterator for &'a AtomDataStorage {
 	type Item = &'a AtomData;
 	type IntoIter = AtomDataStorageIter<'a>;
@@ -118,6 +132,16 @@ impl<'a> Atom<'a> {
 		(&self.data).into_iter()
 	}
 
+	/// Consumes the atom, returning its [`AtomData`]
+	///
+	/// # Examples
+	///
+	/// ```rust
+	/// ```
+	pub fn into_data(self) -> impl Iterator<Item = AtomData> {
+		self.data.into_iter()
+	}
+
 	/// Append a value to the atom
 	pub fn push_data(&mut self, data: AtomData) {
 		match self.data {
@@ -128,6 +152,49 @@ impl<'a> Atom<'a> {
 		}
 	}
 
+	/// Merge the data of another atom into this one
+	///
+	/// NOTE: Both atoms must have the same identifier
+	///
+	/// # Errors
+	///
+	/// * `self.ident()` != `other.ident()`
+	///
+	/// # Examples
+	///
+	/// ```rust
+	/// use lofty::mp4::{Atom, AtomData, AtomIdent};
+	///
+	/// # fn main() -> lofty::Result<()> {
+	/// // Create an artist atom
+	/// let mut atom = Atom::new(
+	/// 	AtomIdent::Fourcc(*b"\x49ART"),
+	/// 	AtomData::UTF8(String::from("foo")),
+	/// );
+	///
+	/// // Create a second and merge it into the first
+	/// let atom2 = Atom::new(
+	/// 	AtomIdent::Fourcc(*b"\x49ART"),
+	/// 	AtomData::UTF8(String::from("bar")),
+	/// );
+	/// atom.merge(atom2)?;
+	///
+	/// // Our first atom now contains the second atom's content
+	/// assert_eq!(atom.data().count(), 2);
+	/// # Ok(()) }
+	/// ```
+	pub fn merge(&mut self, other: Atom<'_>) -> Result<()> {
+		if self.ident != other.ident {
+			err!(AtomMismatch);
+		}
+
+		for data in other.data {
+			self.push_data(data)
+		}
+
+		Ok(())
+	}
+
 	// Used internally, has no correctness checks
 	pub(crate) fn unknown_implicit(ident: AtomIdent<'_>, data: Vec<u8>) -> Self {
 		Self {
@@ -248,7 +315,7 @@ impl AdvisoryRating {
 impl TryFrom<u8> for AdvisoryRating {
 	type Error = u8;
 
-	fn try_from(input: u8) -> Result<Self, Self::Error> {
+	fn try_from(input: u8) -> std::result::Result<Self, Self::Error> {
 		match input {
 			0 => Ok(Self::Inoffensive),
 			1 | 4 => Ok(Self::Explicit),