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//! Private Use Extensions is a list of extensions intended for
6//! private use.
7//!
8//! Those extensions are treated as a pass-through, and no Unicode related
9//! behavior depends on them.
10//!
11//! The main struct for this extension is [`Private`] which is a list of [`Subtag`]s.
12//!
13//! # Examples
14//!
15//! ```
16//! use icu::locid::extensions::private::subtag;
17//! use icu::locid::{locale, Locale};
18//!
19//! let mut loc: Locale = "en-US-x-foo-faa".parse().expect("Parsing failed.");
20//!
21//! assert!(loc.extensions.private.contains(&subtag!("foo")));
22//! assert_eq!(loc.extensions.private.iter().next(), Some(&subtag!("foo")));
23//!
24//! loc.extensions.private.clear();
25//!
26//! assert!(loc.extensions.private.is_empty());
27//! assert_eq!(loc, locale!("en-US"));
28//! ```
29
30mod other;
31
32use alloc::vec::Vec;
33use core::ops::Deref;
34
35#[doc(inline)]
36pub use other::{subtag, Subtag};
37
38use crate::parser::ParserError;
39use crate::parser::SubtagIterator;
40use crate::shortvec::ShortBoxSlice;
41
42/// A list of [`Private Use Extensions`] as defined in [`Unicode Locale
43/// Identifier`] specification.
44///
45/// Those extensions are treated as a pass-through, and no Unicode related
46/// behavior depends on them.
47///
48/// # Examples
49///
50/// ```
51/// use icu::locid::extensions::private::{Private, Subtag};
52///
53/// let subtag1: Subtag = "foo".parse().expect("Failed to parse a Subtag.");
54/// let subtag2: Subtag = "bar".parse().expect("Failed to parse a Subtag.");
55///
56/// let private = Private::from_vec_unchecked(vec![subtag1, subtag2]);
57/// assert_eq!(&private.to_string(), "x-foo-bar");
58/// ```
59///
60/// [`Private Use Extensions`]: https://unicode.org/reports/tr35/#pu_extensions
61/// [`Unicode Locale Identifier`]: https://unicode.org/reports/tr35/#Unicode_locale_identifier
62#[derive(Clone, PartialEq, Eq, Debug, Default, Hash, PartialOrd, Ord)]
63pub struct Private(ShortBoxSlice<Subtag>);
64
65impl Private {
66 /// Returns a new empty list of private-use extensions. Same as [`default()`](Default::default()), but is `const`.
67 ///
68 /// # Examples
69 ///
70 /// ```
71 /// use icu::locid::extensions::private::Private;
72 ///
73 /// assert_eq!(Private::new(), Private::default());
74 /// ```
75 #[inline]
76 pub const fn new() -> Self {
77 Self(ShortBoxSlice::new())
78 }
79
80 /// A constructor which takes a pre-sorted list of [`Subtag`].
81 ///
82 /// # Examples
83 ///
84 /// ```
85 /// use icu::locid::extensions::private::{Private, Subtag};
86 ///
87 /// let subtag1: Subtag = "foo".parse().expect("Failed to parse a Subtag.");
88 /// let subtag2: Subtag = "bar".parse().expect("Failed to parse a Subtag.");
89 ///
90 /// let private = Private::from_vec_unchecked(vec![subtag1, subtag2]);
91 /// assert_eq!(&private.to_string(), "x-foo-bar");
92 /// ```
93 pub fn from_vec_unchecked(input: Vec<Subtag>) -> Self {
94 Self(input.into())
95 }
96
97 /// A constructor which takes a single [`Subtag`].
98 ///
99 /// # Examples
100 ///
101 /// ```
102 /// use icu::locid::extensions::private::{Private, Subtag};
103 ///
104 /// let subtag: Subtag = "foo".parse().expect("Failed to parse a Subtag.");
105 ///
106 /// let private = Private::new_single(subtag);
107 /// assert_eq!(&private.to_string(), "x-foo");
108 /// ```
109 pub const fn new_single(input: Subtag) -> Self {
110 Self(ShortBoxSlice::new_single(input))
111 }
112
113 /// Empties the [`Private`] list.
114 ///
115 /// # Examples
116 ///
117 /// ```
118 /// use icu::locid::extensions::private::{Private, Subtag};
119 ///
120 /// let subtag1: Subtag = "foo".parse().expect("Failed to parse a Subtag.");
121 /// let subtag2: Subtag = "bar".parse().expect("Failed to parse a Subtag.");
122 /// let mut private = Private::from_vec_unchecked(vec![subtag1, subtag2]);
123 ///
124 /// assert_eq!(&private.to_string(), "x-foo-bar");
125 ///
126 /// private.clear();
127 ///
128 /// assert_eq!(private, Private::new());
129 /// ```
130 pub fn clear(&mut self) {
131 self.0.clear();
132 }
133
134 pub(crate) fn try_from_iter(iter: &mut SubtagIterator) -> Result<Self, ParserError> {
135 let keys = iter
136 .map(Subtag::try_from_bytes)
137 .collect::<Result<ShortBoxSlice<_>, _>>()?;
138
139 Ok(Self(keys))
140 }
141
142 pub(crate) fn for_each_subtag_str<E, F>(&self, f: &mut F) -> Result<(), E>
143 where
144 F: FnMut(&str) -> Result<(), E>,
145 {
146 if self.is_empty() {
147 return Ok(());
148 }
149 f("x")?;
150 self.deref().iter().map(|t| t.as_str()).try_for_each(f)
151 }
152}
153
154writeable::impl_display_with_writeable!(Private);
155
156impl writeable::Writeable for Private {
157 fn write_to<W: core::fmt::Write + ?Sized>(&self, sink: &mut W) -> core::fmt::Result {
158 if self.is_empty() {
159 return Ok(());
160 }
161 sink.write_str("x")?;
162 for key: &Subtag in self.iter() {
163 sink.write_char('-')?;
164 writeable::Writeable::write_to(self:key, sink)?;
165 }
166 Ok(())
167 }
168
169 fn writeable_length_hint(&self) -> writeable::LengthHint {
170 if self.is_empty() {
171 return writeable::LengthHint::exact(0);
172 }
173 let mut result: LengthHint = writeable::LengthHint::exact(1);
174 for key: &Subtag in self.iter() {
175 result += writeable::Writeable::writeable_length_hint(self:key) + 1;
176 }
177 result
178 }
179}
180
181impl Deref for Private {
182 type Target = [Subtag];
183
184 fn deref(&self) -> &Self::Target {
185 self.0.deref()
186 }
187}
188