lofty 0.25.4

Audio metadata library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

use crate::ape::constants::INVALID_KEYS;
use crate::ape::tag::error::ApeTagItemValidationError;
use crate::tag::ItemValue;
use crate::tag::item::ItemValueRef;

/// Represents an `APE` tag item
///
/// The restrictions for `APE` lie in the key rather than the value,
/// so these are still able to use [`ItemValue`]s
#[derive(Debug, PartialEq, Eq, Clone)]
pub struct ApeItem {
	/// Whether or not to mark the item as read only
	pub read_only: bool,
	pub(crate) key: String,
	pub(crate) value: ItemValue,
}

impl ApeItem {
	/// Placeholder for conversions
	pub(crate) const EMPTY: Self = ApeItem {
		read_only: false,
		key: String::new(),
		value: ItemValue::Text(String::new()),
	};

	/// Create an [`ApeItem`]
	///
	/// # Errors
	///
	/// * `key` is illegal ("ID3", "TAG", "OGGS", "MP+")
	/// * `key` has a bad length (must be 2 to 255, inclusive)
	/// * `key` contains invalid characters (must be in the range 0x20 to 0x7E, inclusive)
	pub fn new(key: String, value: ItemValue) -> Result<Self, ApeTagItemValidationError> {
		if INVALID_KEYS.iter().any(|k| k.eq_ignore_ascii_case(&key)) {
			return Err(ApeTagItemValidationError::illegal_key(&key));
		}

		if !(2..=255).contains(&key.len()) {
			return Err(ApeTagItemValidationError::invalid_length());
		}

		if key.chars().any(|c| !(0x20..=0x7E).contains(&(c as u32))) {
			return Err(ApeTagItemValidationError::invalid_characters());
		}

		Ok(Self {
			read_only: false,
			key,
			value,
		})
	}

	/// Returns the item key
	pub fn key(&self) -> &str {
		&self.key
	}

	/// Returns the item value
	pub fn value(&self) -> &ItemValue {
		&self.value
	}

	/// Get all text values of this item
	///
	/// This will return `None` for [`ItemValue::Binary`].
	///
	/// ```rust
	/// use lofty::ape::ApeItem;
	/// use lofty::tag::ItemValue;
	///
	/// # fn main() -> Result<(), lofty::ape::error::ApeTagItemValidationError> {
	/// let item = ApeItem::new(
	/// 	String::from("Artist"),
	/// 	ItemValue::Text(String::from("Serial\0ATA")),
	/// )?;
	///
	/// let mut values = item.text_values().expect("should be text");
	/// assert_eq!(values.next(), Some("Serial"));
	/// assert_eq!(values.next(), Some("ATA"));
	/// assert!(values.next().is_none());
	/// # Ok(()) }
	/// ```
	pub fn text_values(&self) -> Option<impl Iterator<Item = &str>> {
		match self.value() {
			ItemValue::Text(text) | ItemValue::Locator(text) => Some(text.split('\0')),
			ItemValue::Binary(_) => None,
		}
	}

	// Used internally, has no correctness checks
	pub(crate) fn text(key: &str, value: String) -> Self {
		Self {
			read_only: false,
			key: String::from(key),
			value: ItemValue::Text(value),
		}
	}
}

pub(crate) struct ApeItemRef<'a> {
	pub read_only: bool,
	pub key: &'a str,
	pub value: ItemValueRef<'a>,
}

impl<'a> Into<ApeItemRef<'a>> for &'a ApeItem {
	fn into(self) -> ApeItemRef<'a> {
		ApeItemRef {
			read_only: self.read_only,
			key: self.key(),
			value: (&self.value).into(),
		}
	}
}