1// This file is part of ICU4X. For terms of use, please see the file
2// called LICENSE at the top level of the ICU4X source tree
3// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ).
4
5macro_rules! impl_tinystr_subtag {
6 (
7 $(#[$doc:meta])*
8 $name:ident,
9 $($path:ident)::+,
10 $macro_name:ident,
11 $legacy_macro_name:ident,
12 $len_start:literal..=$len_end:literal,
13 $tinystr_ident:ident,
14 $validate:expr,
15 $normalize:expr,
16 $is_normalized:expr,
17 $error:ident,
18 [$good_example:literal $(,$more_good_examples:literal)*],
19 [$bad_example:literal $(, $more_bad_examples:literal)*],
20 ) => {
21 #[derive(Debug, PartialEq, Eq, Clone, Hash, PartialOrd, Ord, Copy)]
22 #[cfg_attr(feature = "serde", derive(serde::Serialize))]
23 #[repr(transparent)]
24 $(#[$doc])*
25 pub struct $name(tinystr::TinyAsciiStr<$len_end>);
26
27 impl $name {
28 /// A constructor which takes a UTF-8 slice, parses it and
29 #[doc = concat!("produces a well-formed [`", stringify!($name), "`].")]
30 ///
31 /// # Examples
32 ///
33 /// ```
34 #[doc = concat!("use icu_locid::", stringify!($($path::)+), stringify!($name), ";")]
35 ///
36 #[doc = concat!("assert!(", stringify!($name), "::try_from_bytes(b", stringify!($good_example), ").is_ok());")]
37 #[doc = concat!("assert!(", stringify!($name), "::try_from_bytes(b", stringify!($bad_example), ").is_err());")]
38 /// ```
39 pub const fn try_from_bytes(v: &[u8]) -> Result<Self, crate::parser::errors::ParserError> {
40 Self::try_from_bytes_manual_slice(v, 0, v.len())
41 }
42
43 /// Equivalent to [`try_from_bytes(bytes[start..end])`](Self::try_from_bytes),
44 /// but callable in a `const` context (which range indexing is not).
45 pub const fn try_from_bytes_manual_slice(
46 v: &[u8],
47 start: usize,
48 end: usize,
49 ) -> Result<Self, crate::parser::errors::ParserError> {
50 let slen = end - start;
51
52 #[allow(clippy::double_comparisons)] // if len_start == len_end
53 if slen < $len_start || slen > $len_end {
54 return Err(crate::parser::errors::ParserError::$error);
55 }
56
57 match tinystr::TinyAsciiStr::from_bytes_manual_slice(v, start, end) {
58 Ok($tinystr_ident) if $validate => Ok(Self($normalize)),
59 _ => Err(crate::parser::errors::ParserError::$error),
60 }
61 }
62
63 #[doc = concat!("Safely creates a [`", stringify!($name), "`] from its raw format")]
64 /// as returned by [`Self::into_raw`]. Unlike [`Self::try_from_bytes`],
65 /// this constructor only takes normalized values.
66 pub const fn try_from_raw(
67 v: [u8; $len_end],
68 ) -> Result<Self, crate::parser::errors::ParserError> {
69 if let Ok($tinystr_ident) = tinystr::TinyAsciiStr::<$len_end>::try_from_raw(v) {
70 if $tinystr_ident.len() >= $len_start && $is_normalized {
71 Ok(Self($tinystr_ident))
72 } else {
73 Err(crate::parser::errors::ParserError::$error)
74 }
75 } else {
76 Err(crate::parser::errors::ParserError::$error)
77 }
78 }
79
80 #[doc = concat!("Unsafely creates a [`", stringify!($name), "`] from its raw format")]
81 /// as returned by [`Self::into_raw`]. Unlike [`Self::try_from_bytes`],
82 /// this constructor only takes normalized values.
83 ///
84 /// # Safety
85 ///
86 /// This function is safe iff [`Self::try_from_raw`] returns an `Ok`. This is the case
87 /// for inputs that are correctly normalized.
88 pub const unsafe fn from_raw_unchecked(v: [u8; $len_end]) -> Self {
89 Self(tinystr::TinyAsciiStr::from_bytes_unchecked(v))
90 }
91
92 /// Deconstructs into a raw format to be consumed by
93 /// [`from_raw_unchecked`](Self::from_raw_unchecked()) or
94 /// [`try_from_raw`](Self::try_from_raw()).
95 pub const fn into_raw(self) -> [u8; $len_end] {
96 *self.0.all_bytes()
97 }
98
99 #[inline]
100 /// A helper function for displaying as a `&str`.
101 pub const fn as_str(&self) -> &str {
102 self.0.as_str()
103 }
104
105 #[doc(hidden)]
106 pub const fn into_tinystr(&self) -> tinystr::TinyAsciiStr<$len_end> {
107 self.0
108 }
109
110 /// Compare with BCP-47 bytes.
111 ///
112 /// The return value is equivalent to what would happen if you first converted
113 /// `self` to a BCP-47 string and then performed a byte comparison.
114 ///
115 /// This function is case-sensitive and results in a *total order*, so it is appropriate for
116 /// binary search. The only argument producing [`Ordering::Equal`](core::cmp::Ordering::Equal)
117 /// is `self.as_str().as_bytes()`.
118 #[inline]
119 pub fn strict_cmp(self, other: &[u8]) -> core::cmp::Ordering {
120 self.as_str().as_bytes().cmp(other)
121 }
122
123 /// Compare with a potentially unnormalized BCP-47 string.
124 ///
125 /// The return value is equivalent to what would happen if you first parsed the
126 /// BCP-47 string and then performed a structural comparison.
127 ///
128 #[inline]
129 pub fn normalizing_eq(self, other: &str) -> bool {
130 self.as_str().eq_ignore_ascii_case(other)
131 }
132 }
133
134 impl core::str::FromStr for $name {
135 type Err = crate::parser::errors::ParserError;
136
137 fn from_str(source: &str) -> Result<Self, Self::Err> {
138 Self::try_from_bytes(source.as_bytes())
139 }
140 }
141
142 impl<'l> From<&'l $name> for &'l str {
143 fn from(input: &'l $name) -> Self {
144 input.as_str()
145 }
146 }
147
148 impl From<$name> for tinystr::TinyAsciiStr<$len_end> {
149 fn from(input: $name) -> Self {
150 input.into_tinystr()
151 }
152 }
153
154 impl writeable::Writeable for $name {
155 #[inline]
156 fn write_to<W: core::fmt::Write + ?Sized>(&self, sink: &mut W) -> core::fmt::Result {
157 sink.write_str(self.as_str())
158 }
159 #[inline]
160 fn writeable_length_hint(&self) -> writeable::LengthHint {
161 writeable::LengthHint::exact(self.0.len())
162 }
163 #[inline]
164 fn write_to_string(&self) -> alloc::borrow::Cow<str> {
165 alloc::borrow::Cow::Borrowed(self.0.as_str())
166 }
167 }
168
169 writeable::impl_display_with_writeable!($name);
170
171 #[doc = concat!("A macro allowing for compile-time construction of valid [`", stringify!($name), "`] subtags.")]
172 ///
173 /// # Examples
174 ///
175 /// Parsing errors don't have to be handled at runtime:
176 /// ```
177 /// assert_eq!(
178 #[doc = concat!(" icu_locid::", $(stringify!($path), "::",)+ stringify!($macro_name), "!(", stringify!($good_example) ,"),")]
179 #[doc = concat!(" ", stringify!($good_example), ".parse::<icu_locid::", $(stringify!($path), "::",)+ stringify!($name), ">().unwrap()")]
180 /// );
181 /// ```
182 ///
183 /// Invalid input is a compile failure:
184 /// ```compile_fail,E0080
185 #[doc = concat!("icu_locid::", $(stringify!($path), "::",)+ stringify!($macro_name), "!(", stringify!($bad_example) ,");")]
186 /// ```
187 ///
188 #[doc = concat!("[`", stringify!($name), "`]: crate::", $(stringify!($path), "::",)+ stringify!($name))]
189 #[macro_export]
190 #[doc(hidden)]
191 macro_rules! $legacy_macro_name {
192 ($string:literal) => {{
193 use $crate::$($path ::)+ $name;
194 const R: $name =
195 match $name::try_from_bytes($string.as_bytes()) {
196 Ok(r) => r,
197 #[allow(clippy::panic)] // const context
198 _ => panic!(concat!("Invalid ", $(stringify!($path), "::",)+ stringify!($name), ": ", $string)),
199 };
200 R
201 }};
202 }
203 #[doc(inline)]
204 pub use $legacy_macro_name as $macro_name;
205
206 #[cfg(feature = "databake")]
207 impl databake::Bake for $name {
208 fn bake(&self, env: &databake::CrateEnv) -> databake::TokenStream {
209 env.insert("icu_locid");
210 let string = self.as_str();
211 databake::quote! { icu_locid::$($path::)+ $macro_name!(#string) }
212 }
213 }
214
215 #[test]
216 fn test_construction() {
217 let maybe = $name::try_from_bytes($good_example.as_bytes());
218 assert!(maybe.is_ok());
219 assert_eq!(maybe, $name::try_from_raw(maybe.unwrap().into_raw()));
220 assert_eq!(maybe.unwrap().as_str(), $good_example);
221 $(
222 let maybe = $name::try_from_bytes($more_good_examples.as_bytes());
223 assert!(maybe.is_ok());
224 assert_eq!(maybe, $name::try_from_raw(maybe.unwrap().into_raw()));
225 assert_eq!(maybe.unwrap().as_str(), $more_good_examples);
226 )*
227 assert!($name::try_from_bytes($bad_example.as_bytes()).is_err());
228 $(
229 assert!($name::try_from_bytes($more_bad_examples.as_bytes()).is_err());
230 )*
231 }
232
233 #[test]
234 fn test_writeable() {
235 writeable::assert_writeable_eq!(&$good_example.parse::<$name>().unwrap(), $good_example);
236 $(
237 writeable::assert_writeable_eq!($more_good_examples.parse::<$name>().unwrap(), $more_good_examples);
238 )*
239 }
240
241 #[cfg(feature = "serde")]
242 impl<'de> serde::Deserialize<'de> for $name {
243 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
244 where
245 D: serde::de::Deserializer<'de>,
246 {
247 struct Visitor;
248
249 impl<'de> serde::de::Visitor<'de> for Visitor {
250 type Value = $name;
251
252 fn expecting(
253 &self,
254 formatter: &mut core::fmt::Formatter<'_>,
255 ) -> core::fmt::Result {
256 write!(formatter, "a valid BCP-47 {}", stringify!($name))
257 }
258
259 fn visit_str<E: serde::de::Error>(self, s: &str) -> Result<Self::Value, E> {
260 s.parse().map_err(serde::de::Error::custom)
261 }
262 }
263
264 if deserializer.is_human_readable() {
265 deserializer.deserialize_string(Visitor)
266 } else {
267 Self::try_from_raw(serde::de::Deserialize::deserialize(deserializer)?)
268 .map_err(serde::de::Error::custom)
269 }
270 }
271 }
272
273 // Safety checklist for ULE:
274 //
275 // 1. Must not include any uninitialized or padding bytes (true since transparent over a ULE).
276 // 2. Must have an alignment of 1 byte (true since transparent over a ULE).
277 // 3. ULE::validate_byte_slice() checks that the given byte slice represents a valid slice.
278 // 4. ULE::validate_byte_slice() checks that the given byte slice has a valid length.
279 // 5. All other methods must be left with their default impl.
280 // 6. Byte equality is semantic equality.
281 #[cfg(feature = "zerovec")]
282 unsafe impl zerovec::ule::ULE for $name {
283 fn validate_byte_slice(bytes: &[u8]) -> Result<(), zerovec::ZeroVecError> {
284 let it = bytes.chunks_exact(core::mem::size_of::<Self>());
285 if !it.remainder().is_empty() {
286 return Err(zerovec::ZeroVecError::length::<Self>(bytes.len()));
287 }
288 for v in it {
289 // The following can be removed once `array_chunks` is stabilized.
290 let mut a = [0; core::mem::size_of::<Self>()];
291 a.copy_from_slice(v);
292 if Self::try_from_raw(a).is_err() {
293 return Err(zerovec::ZeroVecError::parse::<Self>());
294 }
295 }
296 Ok(())
297 }
298 }
299
300 #[cfg(feature = "zerovec")]
301 impl zerovec::ule::AsULE for $name {
302 type ULE = Self;
303 fn to_unaligned(self) -> Self::ULE {
304 self
305 }
306 fn from_unaligned(unaligned: Self::ULE) -> Self {
307 unaligned
308 }
309 }
310
311 #[cfg(feature = "zerovec")]
312 impl<'a> zerovec::maps::ZeroMapKV<'a> for $name {
313 type Container = zerovec::ZeroVec<'a, $name>;
314 type Slice = zerovec::ZeroSlice<$name>;
315 type GetType = $name;
316 type OwnedType = $name;
317 }
318 };
319}
320
321macro_rules! impl_writeable_for_each_subtag_str_no_test {
322 ($type:tt $(, $self:ident, $borrow_cond:expr => $borrow:expr)?) => {
323 impl writeable::Writeable for $type {
324 fn write_to<W: core::fmt::Write + ?Sized>(&self, sink: &mut W) -> core::fmt::Result {
325 let mut initial = true;
326 self.for_each_subtag_str(&mut |subtag| {
327 if initial {
328 initial = false;
329 } else {
330 sink.write_char('-')?;
331 }
332 sink.write_str(subtag)
333 })
334 }
335
336 #[inline]
337 fn writeable_length_hint(&self) -> writeable::LengthHint {
338 let mut result = writeable::LengthHint::exact(0);
339 let mut initial = true;
340 self.for_each_subtag_str::<core::convert::Infallible, _>(&mut |subtag| {
341 if initial {
342 initial = false;
343 } else {
344 result += 1;
345 }
346 result += subtag.len();
347 Ok(())
348 })
349 .expect("infallible");
350 result
351 }
352
353 $(
354 fn write_to_string(&self) -> alloc::borrow::Cow<str> {
355 #[allow(clippy::unwrap_used)] // impl_writeable_for_subtag_list's $borrow uses unwrap
356 let $self = self;
357 if $borrow_cond {
358 $borrow
359 } else {
360 let mut output = alloc::string::String::with_capacity(self.writeable_length_hint().capacity());
361 let _ = self.write_to(&mut output);
362 alloc::borrow::Cow::Owned(output)
363 }
364 }
365 )?
366 }
367
368 writeable::impl_display_with_writeable!($type);
369 };
370}
371
372macro_rules! impl_writeable_for_subtag_list {
373 ($type:tt, $sample1:literal, $sample2:literal) => {
374 impl_writeable_for_each_subtag_str_no_test!($type, selff, selff.0.len() == 1 => alloc::borrow::Cow::Borrowed(selff.0.get(0).unwrap().as_str()));
375
376 #[test]
377 fn test_writeable() {
378 writeable::assert_writeable_eq!(&$type::default(), "");
379 writeable::assert_writeable_eq!(
380 &$type::from_short_slice_unchecked(alloc::vec![$sample1.parse().unwrap()].into()),
381 $sample1,
382 );
383 writeable::assert_writeable_eq!(
384 &$type::from_short_slice_unchecked(vec![
385 $sample1.parse().unwrap(),
386 $sample2.parse().unwrap()
387 ].into()),
388 core::concat!($sample1, "-", $sample2),
389 );
390 }
391 };
392}
393
394macro_rules! impl_writeable_for_key_value {
395 ($type:tt, $key1:literal, $value1:literal, $key2:literal, $expected2:literal) => {
396 impl_writeable_for_each_subtag_str_no_test!($type);
397
398 #[test]
399 fn test_writeable() {
400 writeable::assert_writeable_eq!(&$type::default(), "");
401 writeable::assert_writeable_eq!(
402 &$type::from_tuple_vec(vec![($key1.parse().unwrap(), $value1.parse().unwrap())]),
403 core::concat!($key1, "-", $value1),
404 );
405 writeable::assert_writeable_eq!(
406 &$type::from_tuple_vec(vec![
407 ($key1.parse().unwrap(), $value1.parse().unwrap()),
408 ($key2.parse().unwrap(), "true".parse().unwrap())
409 ]),
410 core::concat!($key1, "-", $value1, "-", $expected2),
411 );
412 }
413 };
414}
415