Accessor: Replace *_year() with *_date()

Since almost all formats support full dates, the `Accessor` methods can now accept and return full `Timestamp`s, rather than just a year.

For ID3v1, the timestamp will just be truncated to its year.

This also changes the `year` field of `Id3v1Tag` to a `u16`, rather than a `String`.

Author: Serial-ATA

CHANGELOG.md

@@ -28,6 +28,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 - **ID3v2**: Check `TXXX:ALBUMARTIST` and `TXXX:ALBUM ARTIST` for `ItemKey::AlbumArtist` conversions
+- **ID3v1**: The `year` field in `Id3v1Tag` is now a `u16`, instead of a `String` ([PR](https://github.com/Serial-ATA/lofty-rs/pull/574))
 - **Vorbis Comments**: Check `ALBUM ARTIST` for `ItemKey::AlbumArtist` conversions
 - **Vorbis Comments**: Support `DISCNUMBER` fields with the `current/total` format. ([issue](https://github.com/Serial-ATA/lofty-rs/issues/543)) ([PR](https://github.com/Serial-ATA/lofty-rs/pull/544))
     - These fields will now properly be split into `DISCNUMBER` and `DISCTOTAL`, making it possible to use them with
@@ -51,6 +52,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     * `Tag` is now intended for generic metadata editing only, with format-specific items only being available through concrete tag types.
       See <https://github.com/Serial-ATA/lofty-rs/issues/521> for the rationale.
 * **Picture**: `Picture::new_unchecked()`, replaced with `Picture::unchecked()` returning a builder ([issue](https://github.com/Serial-ATA/lofty-rs/issues/468)) ([PR](https://github.com/Serial-ATA/lofty-rs/pull/569))
+* **Accessor**: `Accessor::*_year()` methods, replaced with `Accessor::*_date()` ([issue](https://github.com/Serial-ATA/lofty-rs/issues/565)) ([PR](https://github.com/Serial-ATA/lofty-rs/pull/574))
+  - Since all formats (*except ID3v1*) have full date support, the generic API now accepts `Timestamp`s. For ID3v1, the date will be truncated
+    down to the year for conversions/writing.
+  - Year tags can still be set manually with `ItemKey::Year`
 
 ## [0.22.4] - 2025-04-29
 

benches/create_tag.rs

@@ -9,6 +9,7 @@ use lofty::iff::wav::RiffInfoList;
 use lofty::mp4::Ilst;
 use lofty::ogg::VorbisComments;
 use lofty::picture::{MimeType, Picture, PictureType};
+use lofty::tag::items::Timestamp;
 use lofty::tag::{Accessor, TagExt};
 
 use std::borrow::Cow;
@@ -28,7 +29,10 @@ macro_rules! bench_tag_write {
 				$tag_.set_artist(String::from("Dave Eddy"));
 				$tag_.set_title(String::from("TempleOS Hymn Risen (Remix)"));
 				$tag_.set_album(String::from("Summer"));
-				$tag_.set_year(2017);
+				$tag_.set_date(Timestamp {
+					year: 2017,
+					..Timestamp::default()
+				});
 				$tag_.set_track(1);
 				$tag_.set_genre(String::from("Electronic"));
 				$extra_block;

lofty/src/ape/tag/mod.rs

@@ -7,8 +7,10 @@ use crate::config::WriteOptions;
 use crate::error::{LoftyError, Result};
 use crate::id3::v2::util::pairs::{NUMBER_PAIR_KEYS, format_number_pair, set_number};
 use crate::tag::item::ItemValueRef;
+use crate::tag::items::Timestamp;
 use crate::tag::{
-	Accessor, ItemKey, ItemValue, MergeTag, SplitTag, Tag, TagExt, TagItem, TagType, try_parse_year,
+	Accessor, ItemKey, ItemValue, MergeTag, SplitTag, Tag, TagExt, TagItem, TagType,
+	try_parse_timestamp,
 };
 use crate::util::flag_item;
 use crate::util::io::{FileLike, Truncate};
@@ -293,23 +295,24 @@ impl Accessor for ApeTag {
 		}
 	}
 
-	fn year(&self) -> Option<u32> {
+	// For some reason, the ecosystem agreed on the key "Year", even for full date strings.
+	fn date(&self) -> Option<Timestamp> {
 		if let Some(ApeItem {
 			value: ItemValue::Text(text),
 			..
 		}) = self.get("Year")
 		{
-			return try_parse_year(text);
+			return try_parse_timestamp(text);
 		}
 
 		None
 	}
 
-	fn set_year(&mut self, value: u32) {
+	fn set_date(&mut self, value: Timestamp) {
 		self.insert(ApeItem::text("Year", value.to_string()));
 	}
 
-	fn remove_year(&mut self) {
+	fn remove_date(&mut self) {
 		self.remove("Year");
 	}
 }

lofty/src/id3/v1/constants.rs

@@ -195,12 +195,14 @@ pub const GENRES: [&str; 192] = [
 ];
 
 use crate::tag::ItemKey;
-pub(crate) const VALID_ITEMKEYS: [ItemKey; 7] = [
+pub(crate) const VALID_ITEMKEYS: [ItemKey; 8] = [
 	ItemKey::TrackTitle,
 	ItemKey::TrackArtist,
 	ItemKey::AlbumTitle,
-	ItemKey::Year,
 	ItemKey::Comment,
 	ItemKey::TrackNumber,
 	ItemKey::Genre,
+	// These two are used identically. ID3v1 is the only format that *only* supports year.
+	ItemKey::Year,
+	ItemKey::RecordingDate,
 ];

lofty/src/id3/v1/read.rs

@@ -17,7 +17,11 @@ pub fn parse_id3v1(reader: [u8; 128]) -> Id3v1Tag {
 	tag.title = decode_text(&reader[..30]);
 	tag.artist = decode_text(&reader[30..60]);
 	tag.album = decode_text(&reader[60..90]);
-	tag.year = decode_text(&reader[90..94]);
+
+	let year = try_parse_year(&reader[90..94]).unwrap_or(0);
+	if year != 0 {
+		tag.year = Some(year);
+	}
 
 	// Determine the range of the comment (30 bytes for ID3v1 and 28 for ID3v1.1)
 	// We check for the null terminator 28 bytes in, and for a non-zero track number after it.
@@ -48,3 +52,13 @@ fn decode_text(data: &[u8]) -> Option<String> {
 
 	if read.is_empty() { None } else { Some(read) }
 }
+
+fn try_parse_year(input: &[u8]) -> Option<u16> {
+	let (num_digits, year) = input
+		.iter()
+		.take_while(|c| (**c).is_ascii_digit())
+		.fold((0usize, 0u16), |(num_digits, year), c| {
+			(num_digits + 1, year * 10 + u16::from(*c - b'0'))
+		});
+	(num_digits == 4).then_some(year)
+}

lofty/src/id3/v1/tag.rs

@@ -1,6 +1,7 @@
 use crate::config::WriteOptions;
 use crate::error::{LoftyError, Result};
 use crate::id3::v1::constants::GENRES;
+use crate::tag::items::Timestamp;
 use crate::tag::{Accessor, ItemKey, ItemValue, MergeTag, SplitTag, Tag, TagExt, TagItem, TagType};
 use crate::util::io::{FileLike, Length, Truncate};
 
@@ -80,8 +81,8 @@ pub struct Id3v1Tag {
 	pub artist: Option<String>,
 	/// Album title, 30 bytes max
 	pub album: Option<String>,
-	/// Release year, 4 bytes max
-	pub year: Option<String>,
+	/// Release year (max 9999)
+	pub year: Option<u16>,
 	/// A short comment
 	///
 	/// The number of bytes differs between versions, but not much.
@@ -186,21 +187,18 @@ impl Accessor for Id3v1Tag {
 		self.comment = None;
 	}
 
-	fn year(&self) -> Option<u32> {
-		if let Some(ref year) = self.year {
-			if let Ok(y) = year.parse() {
-				return Some(y);
-			}
-		}
-
-		None
+	fn date(&self) -> Option<Timestamp> {
+		self.year.map(|year| Timestamp {
+			year,
+			..Default::default()
+		})
 	}
 
-	fn set_year(&mut self, value: u32) {
-		self.year = Some(value.to_string());
+	fn set_date(&mut self, value: Timestamp) {
+		self.year = Some(value.year);
 	}
 
-	fn remove_year(&mut self) {
+	fn remove_date(&mut self) {
 		self.year = None;
 	}
 }
@@ -309,7 +307,9 @@ impl SplitTag for Id3v1Tag {
 		self.album
 			.take()
 			.map(|a| tag.insert_text(ItemKey::AlbumTitle, a));
-		self.year.take().map(|y| tag.insert_text(ItemKey::Year, y));
+		self.year
+			.take()
+			.map(|y| tag.insert_text(ItemKey::Year, y.to_string()));
 		self.comment
 			.take()
 			.map(|c| tag.insert_text(ItemKey::Comment, c));
@@ -350,7 +350,10 @@ impl From<Tag> for Id3v1Tag {
 		let title = input.take_strings(ItemKey::TrackTitle).next();
 		let artist = input.take_strings(ItemKey::TrackArtist).next();
 		let album = input.take_strings(ItemKey::AlbumTitle).next();
-		let year = input.year().map(|y| y.to_string());
+		let year = input
+			.get_string(ItemKey::Year)
+			.and_then(|year| year.parse().ok())
+			.or_else(|| input.date().map(|y| y.year));
 		let comment = input.take_strings(ItemKey::Comment).next();
 		Self {
 			title,
@@ -379,7 +382,7 @@ pub(crate) struct Id3v1TagRef<'a> {
 	pub title: Option<&'a str>,
 	pub artist: Option<&'a str>,
 	pub album: Option<&'a str>,
-	pub year: Option<&'a str>,
+	pub year: Option<u16>,
 	pub comment: Option<&'a str>,
 	pub track_number: Option<u8>,
 	pub genre: Option<u8>,
@@ -391,7 +394,7 @@ impl<'a> Into<Id3v1TagRef<'a>> for &'a Id3v1Tag {
 			title: self.title.as_deref(),
 			artist: self.artist.as_deref(),
 			album: self.album.as_deref(),
-			year: self.year.as_deref(),
+			year: self.year,
 			comment: self.comment.as_deref(),
 			track_number: self.track_number,
 			genre: self.genre,
@@ -405,7 +408,10 @@ impl<'a> Into<Id3v1TagRef<'a>> for &'a Tag {
 			title: self.get_string(ItemKey::TrackTitle),
 			artist: self.get_string(ItemKey::TrackArtist),
 			album: self.get_string(ItemKey::AlbumTitle),
-			year: self.get_string(ItemKey::Year),
+			year: self
+				.get_string(ItemKey::Year)
+				.and_then(|year| year.parse().ok())
+				.or_else(|| self.date().map(|date| date.year)),
 			comment: self.get_string(ItemKey::Comment),
 			track_number: self
 				.get_string(ItemKey::TrackNumber)
@@ -461,6 +467,7 @@ mod tests {
 	use crate::config::WriteOptions;
 	use crate::id3::v1::Id3v1Tag;
 	use crate::prelude::*;
+	use crate::tag::items::Timestamp;
 	use crate::tag::{Tag, TagType};
 
 	#[test_log::test]
@@ -469,7 +476,7 @@ mod tests {
 			title: Some(String::from("Foo title")),
 			artist: Some(String::from("Bar artist")),
 			album: Some(String::from("Baz album")),
-			year: Some(String::from("1984")),
+			year: Some(1984),
 			comment: Some(String::from("Qux comment")),
 			track_number: Some(1),
 			genre: Some(32),
@@ -482,7 +489,7 @@ mod tests {
 	}
 
 	#[test_log::test]
-	fn id3v2_re_read() {
+	fn id3v1_re_read() {
 		let tag = crate::tag::utils::test_utils::read_path("tests/tags/assets/test.id3v1");
 		let parsed_tag = crate::id3::v1::read::parse_id3v1(tag.try_into().unwrap());
 
@@ -519,4 +526,46 @@ mod tests {
 		assert_eq!(id3v1_tag.track_number, Some(1));
 		assert_eq!(id3v1_tag.genre, Some(32));
 	}
+
+	#[test_log::test]
+	fn year_roundtrip() {
+		// via set_date(), which uses `ItemKey::RecordingDate`
+
+		let mut tag = Tag::new(TagType::Id3v1);
+		tag.set_date(Timestamp {
+			year: 1999,
+			month: Some(10),
+			day: Some(11),
+			hour: Some(12),
+			minute: Some(13),
+			second: Some(14),
+		});
+
+		let id3v1_tag: Id3v1Tag = tag.into();
+
+		assert_eq!(id3v1_tag.year, Some(1999));
+		assert_eq!(
+			id3v1_tag.date(),
+			Some(Timestamp {
+				year: 1999,
+				..Timestamp::default()
+			})
+		);
+
+		// via `ItemKey::Year`
+
+		let mut tag = Tag::new(TagType::Id3v1);
+		tag.insert_text(ItemKey::Year, 1999u16.to_string());
+
+		let id3v1_tag: Id3v1Tag = tag.into();
+
+		assert_eq!(id3v1_tag.year, Some(1999));
+		assert_eq!(
+			id3v1_tag.date(),
+			Some(Timestamp {
+				year: 1999,
+				..Timestamp::default()
+			})
+		);
+	}
 }

lofty/src/id3/v1/write.rs

@@ -78,7 +78,23 @@ pub(super) fn encode(tag: &Id3v1TagRef<'_>) -> std::io::Result<Vec<u8>> {
 	let album = resize_string(tag.album, 30)?;
 	writer.write_all(&album)?;
 
-	let year = resize_string(tag.year, 4)?;
+	let mut year = [0; 4];
+	if let Some(year_num) = tag.year {
+		let mut year_num = std::cmp::min(year_num, 9999);
+
+		let mut idx = 3;
+		loop {
+			year[idx] = b'0' + (year_num % 10) as u8;
+			year_num /= 10;
+
+			if idx == 0 {
+				break;
+			}
+
+			idx -= 1;
+		}
+	}
+
 	writer.write_all(&year)?;
 
 	let comment = resize_string(tag.comment, 28)?;

lofty/src/id3/v2/read.rs

@@ -181,6 +181,7 @@ where
 mod tests {
 	use super::parse_id3v2;
 	use crate::config::ParseOptions;
+	use crate::tag::items::Timestamp;
 
 	#[test_log::test]
 	fn zero_size_id3v2() {
@@ -230,7 +231,13 @@ mod tests {
 		assert_eq!(id3v2.title().as_deref(), Some("Foo title"));
 		assert_eq!(id3v2.artist().as_deref(), Some("Bar artist"));
 		assert_eq!(id3v2.comment().as_deref(), Some("Qux comment"));
-		assert_eq!(id3v2.year(), Some(1984));
+		assert_eq!(
+			id3v2.date(),
+			Some(Timestamp {
+				year: 1984,
+				..Default::default()
+			})
+		);
 		assert_eq!(id3v2.track(), Some(1));
 		assert_eq!(id3v2.genre().as_deref(), Some("Classical"));
 	}

lofty/src/id3/v2/tag.rs

@@ -825,21 +825,21 @@ impl Accessor for Id3v2Tag {
 		let _ = self.remove(&GENRE_ID);
 	}
 
-	fn year(&self) -> Option<u32> {
+	fn date(&self) -> Option<Timestamp> {
 		if let Some(Frame::Timestamp(TimestampFrame { timestamp, .. })) =
 			self.get(&RECORDING_TIME_ID)
 		{
-			return Some(u32::from(timestamp.year));
+			return Some(*timestamp);
 		}
 
 		None
 	}
 
-	fn set_year(&mut self, value: u32) {
+	fn set_date(&mut self, value: Timestamp) {
 		self.insert(Frame::text(Cow::Borrowed("TDRC"), value.to_string()));
 	}
 
-	fn remove_year(&mut self) {
+	fn remove_date(&mut self) {
 		let _ = self.remove(&RECORDING_TIME_ID);
 	}
 

lofty/src/id3/v2/write/frame.rs

@@ -1,12 +1,12 @@
 use crate::error::{Id3v2Error, Id3v2ErrorKind, Result};
 use crate::id3::v2::frame::{FrameFlags, FrameRef};
+use crate::id3::v2::tag::GenresIter;
 use crate::id3::v2::util::synchsafe::SynchsafeInteger;
 use crate::id3::v2::{Frame, FrameId, KeyValueFrame, TextInformationFrame};
 use crate::tag::items::Timestamp;
 
 use std::io::Write;
 
-use crate::id3::v2::tag::GenresIter;
 use byteorder::{BigEndian, WriteBytesExt};
 
 pub(in crate::id3::v2) fn create_items<W>(