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}