Skip to main content

utils/
str.rs

1//! String helpers.
2use std::fmt::{Debug, Display};
3use std::fmt::{Formatter, Write};
4use std::hash::Hash;
5use std::num::NonZero;
6
7/// 2 byte [`TinyStr`] using a [`u16`].
8pub type TinyStr2 = TinyStr<NonZero<u16>>;
9/// 4 byte [`TinyStr`] using a [`u32`].
10pub type TinyStr4 = TinyStr<NonZero<u32>>;
11/// 8 byte [`TinyStr`] using a [`u64`].
12pub type TinyStr8 = TinyStr<NonZero<u64>>;
13
14/// A short string packed into a big-endian [`NonZero`] integer.
15///
16/// `TinyStr` stores up to `N` bytes in a single value that fits in a register, enabling
17/// single-instruction equality and ordering comparisons.
18/// The big-endian layout means normal integer comparisons result in lexicographic order.
19///
20/// Strings are NUL-padded. Trailing NUL bytes are indistinguishable from padding, so two inputs
21/// only differing in trailing NULs will be equal.
22///
23/// Empty strings or strings containing all NUL bytes are not representable.
24///
25/// # Examples
26/// ```
27/// # use utils::str::{TinyStr4, TinyStr8};
28/// let s4 = TinyStr4::new(b"abc").unwrap();
29/// assert_eq!(s4.len(), 3);
30/// assert_eq!(format!("{s4}"), "abc");
31/// assert!(s4 < TinyStr4::from_const(b"abd"));
32/// assert!(s4 > TinyStr4::from_const(b"abb"));
33///
34/// let s8 = TinyStr8::new(b"abcdefg").unwrap();
35/// assert_eq!(s8.len(), 7);
36/// assert_eq!(format!("{s8}"), "abcdefg");
37/// assert_eq!(s8, const { TinyStr8::from_const(b"abcdefg") });
38/// ```
39#[must_use]
40#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
41pub struct TinyStr<T: TinyStrInt>(T);
42
43impl<T: TinyStrInt> TinyStr<T> {
44    /// Creates a new `TinyStr` from a byte slice.
45    ///
46    /// Returns [`None`] if the slice is empty, only contains NUL bytes, or is too long.
47    ///
48    /// # Examples
49    /// ```
50    /// # use utils::str::TinyStr4;
51    /// let s = TinyStr4::new(b"abc").unwrap();
52    /// assert_eq!(s.len(), 3);
53    /// assert_eq!(format!("{s}"), "abc");
54    ///
55    /// assert!(TinyStr4::new(b"").is_none());
56    /// assert!(TinyStr4::new(b"abcde").is_none());
57    /// ```
58    pub fn new(s: &[u8]) -> Option<Self> {
59        if s.is_empty() || s.len() > T::LEN {
60            return None;
61        }
62
63        let mut accumulator = T::Raw::default();
64        let mut i = 0;
65        while i < T::LEN && i < s.len() {
66            accumulator = T::set_raw(accumulator, s[i], i);
67            i += 1;
68        }
69
70        T::from_raw(accumulator).map(Self)
71    }
72
73    /// Creates a new `TinyStr` from a raw [`NonZero`] integer.
74    ///
75    /// # Examples
76    /// ```
77    /// # use utils::str::TinyStr4;
78    /// # use std::num::NonZero;
79    /// let raw = NonZero::new(0x61626300).unwrap();
80    /// let s = TinyStr4::from_raw(raw);
81    /// assert_eq!(s.len(), 3);
82    /// assert_eq!(format!("{s}"), "abc");
83    /// ```
84    #[inline]
85    pub const fn from_raw(raw: T) -> Self {
86        TinyStr(raw)
87    }
88
89    /// Returns the number of bytes in the string.
90    ///
91    /// # Examples
92    /// ```
93    /// # use utils::str::TinyStr4;
94    /// assert_eq!(TinyStr4::new(b"a").unwrap().len(), 1);
95    /// assert_eq!(TinyStr4::new(b"ab").unwrap().len(), 2);
96    /// assert_eq!(TinyStr4::new(b"abc").unwrap().len(), 3);
97    /// assert_eq!(TinyStr4::new(b"abcd").unwrap().len(), 4);
98    /// ```
99    #[inline]
100    #[must_use]
101    #[expect(clippy::len_without_is_empty, reason = "TinyStr is never empty")]
102    pub fn len(self) -> usize {
103        let len = T::LEN - (self.0.trailing_zeros() as usize) / 8;
104        #[cfg(feature = "unsafe")]
105        unsafe {
106            std::hint::assert_unchecked(len >= 1);
107            std::hint::assert_unchecked(len <= T::LEN);
108        }
109        len
110    }
111}
112
113/// Writes the string, replacing any invalid UTF-8 sequences with the replacement character.
114///
115/// This is a comparatively expensive operation, requiring the value to be copied onto the stack
116/// and UTF-8 validation.
117///
118/// # Examples
119/// ```
120/// # use utils::str::TinyStr4;
121/// let s = TinyStr4::new(b"abc").unwrap();
122/// assert_eq!(format!("{s}"), "abc");
123///
124/// let invalid = TinyStr4::from_raw(std::num::NonZero::new(0x61FF6200).unwrap());
125/// assert_eq!(format!("{invalid}"), "a\u{FFFD}b");
126/// ```
127impl<T: TinyStrInt> Display for TinyStr<T> {
128    #[cold]
129    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
130        let bytes = self.0.to_be_bytes();
131        let slice = &bytes.as_ref()[..self.len()];
132        for chunk in slice.utf8_chunks() {
133            f.write_str(chunk.valid())?;
134            if !chunk.invalid().is_empty() {
135                f.write_char(char::REPLACEMENT_CHARACTER)?;
136            }
137        }
138        Ok(())
139    }
140}
141
142/// Writes a debug representation of the string.
143///
144/// # Examples
145/// ```
146/// # use utils::str::TinyStr4;
147/// let s = TinyStr4::new(b"abc").unwrap();
148/// assert_eq!(format!("{s:?}"), "TinyStr(\"abc\")");
149///
150/// let invalid = TinyStr4::from_raw(std::num::NonZero::new(0x61FF6200).unwrap());
151/// assert_eq!(format!("{invalid:?}"), "TinyStr([97, 255, 98])");
152/// ```
153impl<T: TinyStrInt> Debug for TinyStr<T> {
154    #[cold]
155    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
156        let bytes = self.0.to_be_bytes();
157        let slice = &bytes.as_ref()[..self.len()];
158        match std::str::from_utf8(slice) {
159            Ok(s) => f.debug_tuple("TinyStr").field(&s).finish(),
160            Err(_) => f.debug_tuple("TinyStr").field(&slice).finish(),
161        }
162    }
163}
164
165/// Helper trait for integer types that can be used as storage for a [`TinyStr`].
166pub trait TinyStrInt: Copy + Clone + Eq + Ord + Hash + Sized {
167    type Bytes: Copy + Default + AsMut<[u8]> + AsRef<[u8]>;
168    type Raw: Copy + Default;
169    const LEN: usize;
170
171    fn to_be_bytes(self) -> Self::Bytes;
172    fn trailing_zeros(self) -> u32;
173    fn set_raw(accumulator: Self::Raw, byte: u8, pos: usize) -> Self::Raw;
174    fn from_raw(raw: Self::Raw) -> Option<Self>;
175    fn len_mask(len: usize) -> Self::Raw;
176    fn from_bytes(bytes: &[u8], mask: Self::Raw) -> Option<Self>;
177}
178
179macro_rules! int_impl {
180    ($t:ident) => {
181        impl TinyStrInt for NonZero<$t> {
182            type Raw = $t;
183            type Bytes = [u8; Self::LEN];
184            const LEN: usize = $t::BITS as usize / 8;
185
186            #[inline]
187            fn to_be_bytes(self) -> Self::Bytes {
188                self.get().to_be_bytes()
189            }
190            #[inline]
191            fn trailing_zeros(self) -> u32 {
192                self.get().trailing_zeros()
193            }
194            #[inline]
195            fn set_raw(accumulator: Self::Raw, byte: u8, pos: usize) -> Self::Raw {
196                accumulator | ($t::from(byte) << ((Self::LEN - 1 - pos) * 8))
197            }
198            #[inline]
199            fn from_raw(raw: Self::Raw) -> Option<Self> {
200                NonZero::new(raw)
201            }
202            #[inline]
203            #[expect(clippy::cast_possible_truncation)]
204            fn len_mask(len: usize) -> Self::Raw {
205                !$t::MAX.unbounded_shr(len as u32 * 8)
206            }
207            #[inline]
208            fn from_bytes(bytes: &[u8], mask: Self::Raw) -> Option<Self> {
209                NonZero::new($t::from_be_bytes(*bytes.first_chunk()?) & mask)
210            }
211        }
212
213        // Workaround for const trait limitations
214        impl TinyStr<NonZero<$t>> {
215            #[doc = concat!(
216                "Creates a `TinyStr` from a byte slice at compile time, panicking if the string is invalid.\n",
217                "\n",
218                "# Examples\n",
219                "```\n",
220                "# use utils::str::TinyStr;\n",
221                "# use std::num::NonZero;\n",
222                "const S: TinyStr<NonZero<", stringify!($t), ">> = TinyStr::<NonZero<", stringify!($t), ">>::from_const(b\"ab\");\n",
223                "assert_eq!(S, TinyStr::new(b\"ab\").unwrap());\n",
224                "assert_eq!(S.to_string(), \"ab\");\n",
225                "assert_eq!(S.len(), 2);\n",
226                "```"
227            )]
228            pub const fn from_const(s: &[u8]) -> Self {
229                const LEN: usize = $t::BITS as usize / 8;
230
231                assert!(!s.is_empty(), "string is empty");
232                assert!(s.len() <= LEN, "string is too long");
233
234                let mut accumulator: $t = 0;
235                let mut i = 0;
236                while i < s.len() {
237                    accumulator |= (s[i] as $t) << ((LEN - 1 - i) * 8);
238                    i += 1;
239                }
240
241                match NonZero::new(accumulator) {
242                    Some(v) => Self::from_raw(v),
243                    None => panic!("string only contains zero bytes"),
244                }
245            }
246        }
247    };
248}
249int_impl!(u16);
250int_impl!(u32);
251int_impl!(u64);
252
253/// Helper trait to map between length `N` and the smallest [`TinyStrInt`] type that can store it.
254///
255/// See [`parser::tinystr`](crate::parser::tinystr).
256pub trait TinyStrLen<const N: usize> {
257    type Int: TinyStrInt;
258}
259impl TinyStrLen<2> for () {
260    type Int = NonZero<u16>;
261}
262impl TinyStrLen<3> for () {
263    type Int = NonZero<u32>;
264}
265impl TinyStrLen<4> for () {
266    type Int = NonZero<u32>;
267}
268impl TinyStrLen<5> for () {
269    type Int = NonZero<u64>;
270}
271impl TinyStrLen<6> for () {
272    type Int = NonZero<u64>;
273}
274impl TinyStrLen<7> for () {
275    type Int = NonZero<u64>;
276}
277impl TinyStrLen<8> for () {
278    type Int = NonZero<u64>;
279}