icu_locid_transform/
directionality.rs

Help
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}
icu_locid_transform/directionality.rs

icu_locid_transform/
directionality.rs
