icu_provider/
request.rs

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
5#[cfg(feature = "alloc")]
6use alloc::borrow::Cow;
7#[cfg(feature = "alloc")]
8use alloc::borrow::ToOwned;
9#[cfg(feature = "alloc")]
10use alloc::boxed::Box;
11#[cfg(feature = "alloc")]
12use alloc::string::String;
13#[cfg(feature = "alloc")]
14use core::cmp::Ordering;
15use core::default::Default;
16use core::fmt;
17use core::fmt::Debug;
18use core::hash::Hash;
19use core::ops::Deref;
20#[cfg(feature = "alloc")]
21use zerovec::ule::VarULE;
22
23pub use icu_locale_core::DataLocale;
24
25/// The request type passed into all data provider implementations.
26#[derive(Default, Debug, Clone, Copy, PartialEq, Eq)]
27#[allow(clippy::exhaustive_structs)] // this type is stable
28pub struct DataRequest<'a> {
29    /// The data identifier for which to load data.
30    ///
31    /// If locale fallback is enabled, the resulting data may be from a different identifier
32    /// than the one requested here.
33    pub id: DataIdentifierBorrowed<'a>,
34    /// Metadata that may affect the behavior of the data provider.
35    pub metadata: DataRequestMetadata,
36}
37
38/// Metadata for data requests. This is currently empty, but it may be extended with options
39/// for tuning locale fallback, buffer layout, and so forth.
40#[derive(Default, Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
41#[non_exhaustive]
42pub struct DataRequestMetadata {
43    /// Silent requests do not log errors. This can be used for exploratory querying, such as fallbacks.
44    pub silent: bool,
45    /// Whether to allow prefix matches for the data marker attributes.
46    pub attributes_prefix_match: bool,
47}
48
49/// The borrowed version of a [`DataIdentifierCow`].
50#[derive(Default, Debug, Clone, Copy, PartialEq, Eq)]
51#[non_exhaustive]
52pub struct DataIdentifierBorrowed<'a> {
53    /// Marker-specific request attributes
54    pub marker_attributes: &'a DataMarkerAttributes,
55    /// The CLDR locale
56    pub locale: &'a DataLocale,
57}
58
59impl fmt::Display for DataIdentifierBorrowed<'_> {
60    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
61        fmt::Display::fmt(self.locale, f)?;
62        if !self.marker_attributes.is_empty() {
63            write!(f, "/{}", self.marker_attributes.as_str())?;
64        }
65        Ok(())
66    }
67}
68
69impl<'a> DataIdentifierBorrowed<'a> {
70    /// Creates a [`DataIdentifierBorrowed`] for a borrowed [`DataLocale`].
71    pub fn for_locale(locale: &'a DataLocale) -> Self {
72        Self {
73            locale,
74            ..Default::default()
75        }
76    }
77
78    /// Creates a [`DataIdentifierBorrowed`] for a borrowed [`DataMarkerAttributes`].
79    pub fn for_marker_attributes(marker_attributes: &'a DataMarkerAttributes) -> Self {
80        Self {
81            marker_attributes,
82            ..Default::default()
83        }
84    }
85
86    /// Creates a [`DataIdentifierBorrowed`] for a borrowed [`DataMarkerAttributes`] and [`DataLocale`].
87    pub fn for_marker_attributes_and_locale(
88        marker_attributes: &'a DataMarkerAttributes,
89        locale: &'a DataLocale,
90    ) -> Self {
91        Self {
92            marker_attributes,
93            locale,
94        }
95    }
96
97    /// Converts this [`DataIdentifierBorrowed`] into a [`DataIdentifierCow<'static>`].
98    ///
99    /// ✨ *Enabled with the `alloc` Cargo feature.*
100    #[cfg(feature = "alloc")]
101    pub fn into_owned(self) -> DataIdentifierCow<'static> {
102        DataIdentifierCow {
103            marker_attributes: Cow::Owned(self.marker_attributes.to_owned()),
104            locale: *self.locale,
105        }
106    }
107
108    /// Borrows this [`DataIdentifierBorrowed`] as a [`DataIdentifierCow<'a>`].
109    ///
110    /// ✨ *Enabled with the `alloc` Cargo feature.*
111    #[cfg(feature = "alloc")]
112    pub fn as_cow(self) -> DataIdentifierCow<'a> {
113        DataIdentifierCow {
114            marker_attributes: Cow::Borrowed(self.marker_attributes),
115            locale: *self.locale,
116        }
117    }
118}
119
120/// A data identifier identifies a particular version of data, such as "English".
121///
122/// It is a wrapper around a [`DataLocale`] and a [`DataMarkerAttributes`].
123///
124/// ✨ *Enabled with the `alloc` Cargo feature.*
125#[derive(Debug, PartialEq, Eq, Hash, Clone)]
126#[non_exhaustive]
127#[cfg(feature = "alloc")]
128pub struct DataIdentifierCow<'a> {
129    /// Marker-specific request attributes
130    pub marker_attributes: Cow<'a, DataMarkerAttributes>,
131    /// The CLDR locale
132    pub locale: DataLocale,
133}
134
135#[cfg(feature = "alloc")]
136impl PartialOrd for DataIdentifierCow<'_> {
137    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
138        Some(self.cmp(other))
139    }
140}
141
142#[cfg(feature = "alloc")]
143impl Ord for DataIdentifierCow<'_> {
144    fn cmp(&self, other: &Self) -> Ordering {
145        self.marker_attributes
146            .cmp(&other.marker_attributes)
147            .then_with(|| self.locale.total_cmp(&other.locale))
148    }
149}
150
151#[cfg(feature = "alloc")]
152impl fmt::Display for DataIdentifierCow<'_> {
153    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
154        fmt::Display::fmt(&self.locale, f)?;
155        if !self.marker_attributes.is_empty() {
156            write!(f, "/{}", self.marker_attributes.as_str())?;
157        }
158        Ok(())
159    }
160}
161
162#[cfg(feature = "alloc")]
163impl<'a> DataIdentifierCow<'a> {
164    /// Borrows this [`DataIdentifierCow`] as a [`DataIdentifierBorrowed<'a>`].
165    pub fn as_borrowed(&'a self) -> DataIdentifierBorrowed<'a> {
166        DataIdentifierBorrowed {
167            marker_attributes: &self.marker_attributes,
168            locale: &self.locale,
169        }
170    }
171
172    /// Creates a [`DataIdentifierCow`] from an owned [`DataLocale`].
173    pub fn from_locale(locale: DataLocale) -> Self {
174        Self {
175            marker_attributes: Cow::Borrowed(DataMarkerAttributes::empty()),
176            locale,
177        }
178    }
179
180    /// Creates a [`DataIdentifierCow`] from a borrowed [`DataMarkerAttributes`].
181    pub fn from_marker_attributes(marker_attributes: &'a DataMarkerAttributes) -> Self {
182        Self {
183            marker_attributes: Cow::Borrowed(marker_attributes),
184            locale: Default::default(),
185        }
186    }
187
188    /// Creates a [`DataIdentifierCow`] from an owned [`DataMarkerAttributes`].
189    pub fn from_marker_attributes_owned(marker_attributes: Box<DataMarkerAttributes>) -> Self {
190        Self {
191            marker_attributes: Cow::Owned(marker_attributes),
192            locale: Default::default(),
193        }
194    }
195
196    /// Creates a [`DataIdentifierCow`] from an owned [`DataMarkerAttributes`] and an owned [`DataLocale`].
197    pub fn from_owned(marker_attributes: Box<DataMarkerAttributes>, locale: DataLocale) -> Self {
198        Self {
199            marker_attributes: Cow::Owned(marker_attributes),
200            locale,
201        }
202    }
203
204    /// Creates a [`DataIdentifierCow`] from a borrowed [`DataMarkerAttributes`] and an owned [`DataLocale`].
205    pub fn from_borrowed_and_owned(
206        marker_attributes: &'a DataMarkerAttributes,
207        locale: DataLocale,
208    ) -> Self {
209        Self {
210            marker_attributes: Cow::Borrowed(marker_attributes),
211            locale,
212        }
213    }
214
215    /// Returns whether this id is equal to the default.
216    pub fn is_unknown(&self) -> bool {
217        self.marker_attributes.is_empty() && self.locale.is_unknown()
218    }
219}
220
221#[cfg(feature = "alloc")]
222impl Default for DataIdentifierCow<'_> {
223    fn default() -> Self {
224        Self {
225            marker_attributes: Cow::Borrowed(Default::default()),
226            locale: Default::default(),
227        }
228    }
229}
230
231/// An additional key to identify data beyond a [`DataLocale`].
232///
233/// The is a loose wrapper around a string, with semantics defined by each [`DataMarker`](crate::DataMarker).
234#[derive(PartialEq, Eq, Ord, PartialOrd, Hash)]
235#[repr(transparent)]
236pub struct DataMarkerAttributes {
237    // Validated to be non-empty ASCII alphanumeric + hyphen + underscore + forward slash. Disallows leading, trailing, and double slashes.
238    value: str,
239}
240
241impl Default for &DataMarkerAttributes {
242    fn default() -> Self {
243        DataMarkerAttributes::empty()
244    }
245}
246
247impl Deref for DataMarkerAttributes {
248    type Target = str;
249    #[inline]
250    fn deref(&self) -> &Self::Target {
251        &self.value
252    }
253}
254
255impl Debug for DataMarkerAttributes {
256    #[inline]
257    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
258        self.value.fmt(f)
259    }
260}
261
262/// Invalid character
263#[derive(Debug)]
264#[non_exhaustive]
265pub struct AttributeParseError;
266
267impl DataMarkerAttributes {
268    /// Safety-usable invariant: validated bytes are ASCII only
269    const fn validate(s: &[u8]) -> Result<(), AttributeParseError> {
270        if s.is_empty() {
271            return Ok(());
272        }
273        let mut i = 0;
274        // Initialized to true in order to prevent leading slashes
275        let mut prev_was_slash = true;
276        while i < s.len() {
277            #[expect(clippy::indexing_slicing)] // duh
278            let c = s[i];
279            if !matches!(c, b'a'..=b'z' | b'A'..=b'Z' | b'0'..=b'9' | b'-' | b'_' | b'/') {
280                return Err(AttributeParseError);
281            }
282            if c == b'/' {
283                if prev_was_slash {
284                    return Err(AttributeParseError);
285                }
286                prev_was_slash = true;
287            } else {
288                prev_was_slash = false;
289            }
290            i += 1;
291        }
292        // If the last character was a slash, it's a trailing slash, which is disallowed.
293        if prev_was_slash {
294            return Err(AttributeParseError);
295        }
296        Ok(())
297    }
298
299    /// Creates a borrowed [`DataMarkerAttributes`] from a borrowed string.
300    ///
301    /// Returns an error if the string contains characters other than `[a-zA-Z0-9_\-/]`.
302    pub const fn try_from_str(s: &str) -> Result<&Self, AttributeParseError> {
303        Self::try_from_utf8(s.as_bytes())
304    }
305
306    /// Attempts to create a borrowed [`DataMarkerAttributes`] from a borrowed UTF-8 encoded byte slice.
307    ///
308    /// # Examples
309    ///
310    /// ```
311    /// use icu_provider::prelude::*;
312    ///
313    /// let bytes = b"long-meter";
314    /// let marker = DataMarkerAttributes::try_from_utf8(bytes).unwrap();
315    /// assert_eq!(marker.to_string(), "long-meter");
316    /// ```
317    ///
318    /// # Errors
319    ///
320    /// Returns an error if the byte slice contains code units other than `[a-zA-Z0-9_\-/]`.
321    pub const fn try_from_utf8(code_units: &[u8]) -> Result<&Self, AttributeParseError> {
322        let Ok(()) = Self::validate(code_units) else {
323            return Err(AttributeParseError);
324        };
325
326        // SAFETY: `validate` requires a UTF-8 subset
327        let s = unsafe { core::str::from_utf8_unchecked(code_units) };
328
329        // SAFETY: `Self` has the same layout as `str`
330        Ok(unsafe { &*(s as *const str as *const Self) })
331    }
332
333    /// Creates an owned [`DataMarkerAttributes`] from an owned string.
334    ///
335    /// Returns an error if the string contains characters other than `[a-zA-Z0-9_\-/]`.
336    ///
337    /// ✨ *Enabled with the `alloc` Cargo feature.*
338    #[cfg(feature = "alloc")]
339    pub fn try_from_string(s: String) -> Result<Box<Self>, AttributeParseError> {
340        let Ok(()) = Self::validate(s.as_bytes()) else {
341            return Err(AttributeParseError);
342        };
343
344        let boxed = s.into_boxed_str();
345        // Safety: Box::into_raw fulfils Box::from_raw's requirements, as DataMarkerAttributes is
346        // repr(transparent) over str, and its (non-safety) validity constraints were validated above
347        Ok(unsafe { Box::from_raw(Box::into_raw(boxed) as *mut Self) })
348    }
349
350    /// Creates a borrowed [`DataMarkerAttributes`] from a borrowed string.
351    ///
352    /// Panics if the string contains characters other than `[a-zA-Z0-9_\-/]`.
353    pub const fn from_str_or_panic(s: &str) -> &Self {
354        #[allow(clippy::panic)] // documented
355        let Ok(r) = Self::try_from_str(s) else {
356            panic!("Invalid marker attribute syntax")
357        };
358        r
359    }
360
361    /// Creates an empty [`DataMarkerAttributes`].
362    pub const fn empty() -> &'static Self {
363        // SAFETY: `Self` has the same layout as `str`
364        unsafe { &*("" as *const str as *const Self) }
365    }
366
367    /// Returns this [`DataMarkerAttributes`] as a `&str`.
368    pub const fn as_str(&self) -> &str {
369        &self.value
370    }
371}
372
373/// ✨ *Enabled with the `alloc` Cargo feature.*
374#[cfg(feature = "alloc")]
375impl ToOwned for DataMarkerAttributes {
376    type Owned = Box<Self>;
377    fn to_owned(&self) -> Self::Owned {
378        let boxed = self.as_str().to_boxed();
379        // Safety: Box::into_raw fulfils Box::from_raw's requirements, as DataMarkerAttributes is
380        // repr(transparent) over str, and `str` has strictly fewer validity constraints than DataMarkerAttributes
381        unsafe { Box::from_raw(Box::into_raw(boxed) as *mut Self) }
382    }
383}
384
385#[test]
386fn test_data_marker_attributes_from_utf8() {
387    let bytes_vec: Vec<&[u8]> = vec![
388        b"long-meter",
389        b"long",
390        b"meter",
391        b"short-meter-second",
392        b"usd",
393    ];
394
395    for bytes in bytes_vec {
396        let marker = DataMarkerAttributes::try_from_utf8(bytes).unwrap();
397        assert_eq!(marker.to_string().as_bytes(), bytes);
398    }
399}
400
401#[test]
402fn test_data_marker_attributes_syntax() {
403    let valid_cases = [
404        "long-meter",
405        "long",
406        "meter",
407        "short-meter-second",
408        "usd",
409        "nested/part",
410        "foo/bar/baz",
411        "",
412    ];
413
414    let invalid_cases = [
415        "/leading",
416        "trailing/",
417        "double//slash",
418        "invalid space",
419        "invalid$character",
420        "invalid\\backslash",
421    ];
422
423    for s in valid_cases {
424        assert!(
425            DataMarkerAttributes::try_from_str(s).is_ok(),
426            "Expected valid: {}",
427            s
428        );
429    }
430
431    for s in invalid_cases {
432        assert!(
433            DataMarkerAttributes::try_from_str(s).is_err(),
434            "Expected invalid: {}",
435            s
436        );
437    }
438}
icu_provider/request.rs

icu_provider/
request.rs
