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
5use crate::provider::*;
6use crate::{LocaleExpander, LocaleTransformError};
7use icu_locid::subtags::Script;
8use icu_locid::LanguageIdentifier;
9use icu_provider::prelude::*;
10
11/// Represents the direction of a script.
12///
13/// [`LocaleDirectionality`] can be used to get this information.
14#[derive(Debug, PartialEq, Eq, Clone, Copy)]
15#[non_exhaustive]
16pub enum Direction {
17 /// The script is left-to-right.
18 LeftToRight,
19 /// The script is right-to-left.
20 RightToLeft,
21}
22
23/// Provides methods to determine the direction of a locale.
24///
25/// # Examples
26///
27/// ```
28/// use icu::locid::locale;
29/// use icu::locid_transform::{Direction, LocaleDirectionality};
30///
31/// let ld = LocaleDirectionality::new();
32///
33/// assert_eq!(ld.get(&locale!("en")), Some(Direction::LeftToRight));
34/// ```
35#[derive(Debug)]
36pub struct LocaleDirectionality {
37 script_direction: DataPayload<ScriptDirectionV1Marker>,
38 expander: LocaleExpander,
39}
40
41#[cfg(feature = "compiled_data")]
42impl Default for LocaleDirectionality {
43 fn default() -> Self {
44 Self::new()
45 }
46}
47
48impl LocaleDirectionality {
49 /// Creates a [`LocaleDirectionality`] from compiled data.
50 ///
51 /// This includes limited likely subtags data, see [`LocaleExpander::new()`].
52 #[cfg(feature = "compiled_data")]
53 pub const fn new() -> Self {
54 Self::new_with_expander(LocaleExpander::new())
55 }
56
57 // Note: This is a custom impl because the bounds on `try_new_unstable` don't suffice
58 #[doc = icu_provider::gen_any_buffer_unstable_docs!(ANY, Self::new)]
59 pub fn try_new_with_any_provider(
60 provider: &(impl AnyProvider + ?Sized),
61 ) -> Result<LocaleDirectionality, LocaleTransformError> {
62 let expander = LocaleExpander::try_new_with_any_provider(provider)?;
63 Self::try_new_with_expander_unstable(&provider.as_downcasting(), expander)
64 }
65
66 // Note: This is a custom impl because the bounds on `try_new_unstable` don't suffice
67 #[doc = icu_provider::gen_any_buffer_unstable_docs!(BUFFER, Self::new)]
68 #[cfg(feature = "serde")]
69 pub fn try_new_with_buffer_provider(
70 provider: &(impl BufferProvider + ?Sized),
71 ) -> Result<LocaleDirectionality, LocaleTransformError> {
72 let expander = LocaleExpander::try_new_with_buffer_provider(provider)?;
73 Self::try_new_with_expander_unstable(&provider.as_deserializing(), expander)
74 }
75
76 #[doc = icu_provider::gen_any_buffer_unstable_docs!(UNSTABLE, Self::new)]
77 pub fn try_new_unstable<P>(provider: &P) -> Result<LocaleDirectionality, LocaleTransformError>
78 where
79 P: DataProvider<ScriptDirectionV1Marker>
80 + DataProvider<LikelySubtagsForLanguageV1Marker>
81 + DataProvider<LikelySubtagsForScriptRegionV1Marker>
82 + ?Sized,
83 {
84 let expander = LocaleExpander::try_new_unstable(provider)?;
85 Self::try_new_with_expander_unstable(provider, expander)
86 }
87
88 /// Creates a [`LocaleDirectionality`] with a custom [`LocaleExpander`] and compiled data.
89 ///
90 /// This allows using [`LocaleExpander::new_extended()`] with data for all locales.
91 ///
92 /// # Examples
93 ///
94 /// ```
95 /// use icu::locid::locale;
96 /// use icu::locid_transform::{
97 /// Direction, LocaleDirectionality, LocaleExpander,
98 /// };
99 ///
100 /// let ld_default = LocaleDirectionality::new();
101 ///
102 /// assert_eq!(ld_default.get(&locale!("jbn")), None);
103 ///
104 /// let expander = LocaleExpander::new_extended();
105 /// let ld_extended = LocaleDirectionality::new_with_expander(expander);
106 ///
107 /// assert_eq!(
108 /// ld_extended.get(&locale!("jbn")),
109 /// Some(Direction::RightToLeft)
110 /// );
111 /// ```
112 #[cfg(feature = "compiled_data")]
113 pub const fn new_with_expander(expander: LocaleExpander) -> Self {
114 LocaleDirectionality {
115 script_direction: DataPayload::from_static_ref(
116 crate::provider::Baked::SINGLETON_LOCID_TRANSFORM_SCRIPT_DIR_V1,
117 ),
118 expander,
119 }
120 }
121
122 #[doc = icu_provider::gen_any_buffer_unstable_docs!(UNSTABLE, Self::new_with_expander)]
123 pub fn try_new_with_expander_unstable<P>(
124 provider: &P,
125 expander: LocaleExpander,
126 ) -> Result<LocaleDirectionality, LocaleTransformError>
127 where
128 P: DataProvider<ScriptDirectionV1Marker> + ?Sized,
129 {
130 let script_direction = provider.load(Default::default())?.take_payload()?;
131
132 Ok(LocaleDirectionality {
133 script_direction,
134 expander,
135 })
136 }
137
138 /// Returns the script direction of the given locale.
139 ///
140 /// Note that the direction is a property of the script of a locale, not of the language. As such,
141 /// when given a locale without an associated script tag (i.e., `locale!("en")` vs. `locale!("en-Latn")`),
142 /// this method first tries to infer the script using the language and region before returning its direction.
143 ///
144 /// If you already have a script struct and want to get its direction, you should use
145 /// `Locale::from(Some(my_script))` and call this method.
146 ///
147 /// This method will return `None` if either a locale's script cannot be determined, or there is no information
148 /// for the script.
149 ///
150 /// # Examples
151 ///
152 /// Using an existing locale:
153 ///
154 /// ```
155 /// use icu::locid::locale;
156 /// use icu::locid_transform::{Direction, LocaleDirectionality};
157 ///
158 /// let ld = LocaleDirectionality::new();
159 ///
160 /// assert_eq!(ld.get(&locale!("en-US")), Some(Direction::LeftToRight));
161 ///
162 /// assert_eq!(ld.get(&locale!("ar")), Some(Direction::RightToLeft));
163 ///
164 /// assert_eq!(ld.get(&locale!("en-Arab")), Some(Direction::RightToLeft));
165 ///
166 /// assert_eq!(ld.get(&locale!("foo")), None);
167 /// ```
168 ///
169 /// Using a script directly:
170 ///
171 /// ```
172 /// use icu::locid::subtags::script;
173 /// use icu::locid::Locale;
174 /// use icu::locid_transform::{Direction, LocaleDirectionality};
175 ///
176 /// let ld = LocaleDirectionality::new();
177 ///
178 /// assert_eq!(
179 /// ld.get(&Locale::from(Some(script!("Latn")))),
180 /// Some(Direction::LeftToRight)
181 /// );
182 /// ```
183 pub fn get(&self, locale: impl AsRef<LanguageIdentifier>) -> Option<Direction> {
184 let script = self.expander.get_likely_script(locale.as_ref())?;
185
186 if self.script_in_ltr(script) {
187 Some(Direction::LeftToRight)
188 } else if self.script_in_rtl(script) {
189 Some(Direction::RightToLeft)
190 } else {
191 None
192 }
193 }
194
195 /// Returns whether the given locale is right-to-left.
196 ///
197 /// Note that if this method returns `false`, the locale is either left-to-right or
198 /// the [`LocaleDirectionality`] does not include data for the locale.
199 /// You should use [`LocaleDirectionality::get`] if you need to differentiate between these cases.
200 ///
201 /// See [`LocaleDirectionality::get`] for more information.
202 pub fn is_right_to_left(&self, locale: impl AsRef<LanguageIdentifier>) -> bool {
203 self.expander
204 .get_likely_script(locale.as_ref())
205 .map(|s| self.script_in_rtl(s))
206 .unwrap_or(false)
207 }
208
209 /// Returns whether the given locale is left-to-right.
210 ///
211 /// Note that if this method returns `false`, the locale is either right-to-left or
212 /// the [`LocaleDirectionality`] does not include data for the locale.
213 /// You should use [`LocaleDirectionality::get`] if you need to differentiate between these cases.
214 ///
215 /// See [`LocaleDirectionality::get`] for more information.
216 pub fn is_left_to_right(&self, locale: impl AsRef<LanguageIdentifier>) -> bool {
217 self.expander
218 .get_likely_script(locale.as_ref())
219 .map(|s| self.script_in_ltr(s))
220 .unwrap_or(false)
221 }
222
223 fn script_in_rtl(&self, script: Script) -> bool {
224 self.script_direction
225 .get()
226 .rtl
227 .binary_search(&script.into_tinystr().to_unvalidated())
228 .is_ok()
229 }
230
231 fn script_in_ltr(&self, script: Script) -> bool {
232 self.script_direction
233 .get()
234 .ltr
235 .binary_search(&script.into_tinystr().to_unvalidated())
236 .is_ok()
237 }
238}
239