Skip to main content

atom_set/
lib.rs

1#![doc = include_str!("../README.md")]
2
3/// Object-safe version of AtomSet for use with trait objects. This trait mirrors the functionality of AtomSet but is
4/// compatible with `dyn` trait objects.
5pub trait DynAtomSet: std::fmt::Debug {
6	/// Converts a string keyword to the corresponding atom variant, returning its bit representation.
7	fn str_to_bits(&self, keyword: &str) -> u32;
8
9	/// Converts this atom's bit representation back to its string representation.
10	fn bits_to_str(&self, bits: u32) -> &'static str;
11
12	/// Get the current bits of this Atom.
13	fn bits(&self) -> u32;
14}
15
16/// # Usage with `#[derive(AtomSet)]`
17///
18/// The easiest way to implement this trait is using the `AtomSet` derive macro:
19///
20/// ```rust
21/// use derive_atom_set::AtomSet;
22/// use atom_set::AtomSet;
23///
24/// #[derive(Debug, Default, Copy, Clone, PartialEq, AtomSet)]
25/// pub enum Units {
26///   // AtomSet must derive default, ideally with an empty atom, or equivalent!
27///   #[default]
28///   _None,
29///
30///   // Automatically converts to "px"
31///   Px,
32///
33///   // Automatically converts to "rem"
34///   Rem,
35///
36///   // Custom string mapping
37///   #[atom("%")]
38///   Percent,
39/// }
40/// ```
41pub trait AtomSet: Default + std::fmt::Debug {
42	/// Converts a string keyword to the corresponding atom variant.
43	///
44	/// This performs ASCII case-insensitive matching, unless the set is derived with
45	/// `#[atom_set(case_sensitive)]`, and returns the `Empty` variant for unrecognized strings.
46	///
47	/// # Examples
48	///
49	/// ```rust
50	/// # use atom_set::AtomSet;
51	/// use derive_atom_set::*;
52	///
53	/// #[derive(Debug, Default, Copy, Clone, PartialEq, AtomSet)]
54	/// enum MyAtomSet {
55	///   #[default]
56	///   _None,
57	///   Url
58	/// }
59	/// assert_eq!(MyAtomSet::from_str("url"), MyAtomSet::Url);
60	/// assert_eq!(MyAtomSet::from_str("URL"), MyAtomSet::Url);  // Case insensitive
61	/// assert_eq!(MyAtomSet::from_str("unknown"), MyAtomSet::_None);
62	/// ```
63	fn from_str(keyword: &str) -> Self;
64
65	/// Converts this atom back to its string representation.
66	///
67	/// Returns a static string slice that represents this atom's canonical form.
68	///
69	/// The variant marked `#[default]` will always return the empty string.
70	///
71	/// # Examples
72	///
73	/// ```rust
74	/// # use atom_set::AtomSet;
75	/// use derive_atom_set::*;
76	///
77	/// #[derive(Debug, Default, Copy, Clone, PartialEq, AtomSet)]
78	/// enum MyAtomSet {
79	///   #[default]
80	///   _None,
81	///   Url
82	/// }
83	/// assert_eq!(MyAtomSet::Url.to_str(), "url");
84	/// assert_eq!(MyAtomSet::_None.to_str(), "");
85	///
86	/// // Round-trip conversion
87	/// let atom = MyAtomSet::from_str("url");
88	/// assert_eq!(atom.to_str(), "url");
89	/// ```
90	fn to_str(self) -> &'static str;
91
92	/// Returns the length in characters of this atom's string representation.
93	///
94	/// This is equivalent to `self.to_str().len()` but may be more efficient depending on the implementation.
95	///
96	/// # Examples
97	///
98	/// ```rust
99	/// # use atom_set::AtomSet;
100	/// use derive_atom_set::*;
101	///
102	/// #[derive(Debug, Default, Copy, Clone, PartialEq, AtomSet)]
103	/// enum MyAtomSet {
104	///   #[default]
105	///   _None,
106	///   Url
107	/// }
108	/// assert_eq!(MyAtomSet::Url.len(), 3);
109	/// assert_eq!(MyAtomSet::_None.len(), 0);
110	/// ```
111	fn len(&self) -> u32;
112
113	/// Returns true if the length of this atom is 0.
114	///
115	/// This is equivalent to `self.to_str().is_empty()` but may be more efficient depending on the implementation.
116	///
117	/// # Examples
118	///
119	/// ```rust
120	/// # use atom_set::AtomSet;
121	/// use derive_atom_set::*;
122	///
123	/// #[derive(Debug, Default, Copy, Clone, PartialEq, AtomSet)]
124	/// enum MyAtomSet {
125	///   #[default]
126	///   _None,
127	///   Url
128	/// }
129	/// assert!(!MyAtomSet::Url.is_empty());
130	/// assert!(MyAtomSet::_None.is_empty());
131	/// ```
132	fn is_empty(&self) -> bool {
133		self.len() == 0
134	}
135
136	/// Converts a numeric bit representation back to an atom variant.
137	///
138	/// This is used internally for efficient storage and retrieval. Returns the `Empty` variant for unrecognized bit
139	/// values.
140	///
141	/// # Examples
142	///
143	/// ```rust
144	/// # use atom_set::AtomSet;
145	/// use derive_atom_set::*;
146	///
147	/// #[derive(Debug, Default, Copy, Clone, PartialEq, AtomSet)]
148	/// enum MyAtomSet {
149	///   #[default]
150	///   _None,
151	///   Url
152	/// }
153	/// let atom = MyAtomSet::Url;
154	/// let bits = atom.as_bits();
155	/// let restored = MyAtomSet::from_bits(bits);
156	/// assert_eq!(atom, restored);
157	/// ```
158	fn from_bits(bits: u32) -> Self;
159
160	/// Converts this atom to its numeric bit representation.
161	///
162	/// This is used internally for efficient storage. The bit value corresponds to the enum discriminant.
163	///
164	/// # Examples
165	///
166	/// ```rust
167	/// # use atom_set::AtomSet;
168	/// use derive_atom_set::*;
169	///
170	/// #[derive(Debug, Default, Copy, Clone, PartialEq, AtomSet)]
171	/// enum MyAtomSet {
172	///   #[default]
173	///   _None,
174	///   Url
175	/// }
176	/// let bits = MyAtomSet::Url.as_bits();
177	/// assert_eq!(MyAtomSet::from_bits(bits), MyAtomSet::Url);
178	/// ```
179	fn as_bits(&self) -> u32;
180}
181
182/// Blanket implementation so any AtomSet can be used as a DynAtomSet
183impl<T: AtomSet + Clone + 'static> DynAtomSet for T {
184	fn str_to_bits(&self, keyword: &str) -> u32 {
185		T::from_str(keyword).as_bits()
186	}
187
188	fn bits_to_str(&self, bits: u32) -> &'static str {
189		T::from_bits(bits).to_str()
190	}
191
192	fn bits(&self) -> u32 {
193		self.clone().as_bits()
194	}
195}