|
| 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 | +use crate::provider::*; |
| 6 | +use crate::{LocaleExpander, LocaleTransformError}; |
| 7 | +use icu_locid::subtags::Script; |
| 8 | +use icu_locid::Locale; |
| 9 | +use 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] |
| 16 | +pub enum Direction { |
| 17 | + /// The script is left-to-right. |
| 18 | + LeftToRight, |
| 19 | + /// The script is right-to-left. |
| 20 | + RightToLeft, |
| 21 | +} |
| 22 | + |
| 23 | +/// The `LocaleDirectionality` provides methods to determine the direction of a locale based |
| 24 | +/// on [`CLDR`] data. |
| 25 | +/// |
| 26 | +/// # Examples |
| 27 | +/// |
| 28 | +/// ``` |
| 29 | +/// use icu_locid::locale; |
| 30 | +/// use icu_locid_transform::{Direction, LocaleDirectionality}; |
| 31 | +/// |
| 32 | +/// let ld = LocaleDirectionality::try_new_unstable(&icu_testdata::unstable()) |
| 33 | +/// .expect("create failed"); |
| 34 | +/// |
| 35 | +/// assert_eq!(ld.get(&locale!("en")), Some(Direction::LeftToRight)); |
| 36 | +/// ``` |
| 37 | +/// |
| 38 | +/// [`CLDR`]: http://cldr.unicode.org/ |
| 39 | +#[derive(Debug)] |
| 40 | +pub struct LocaleDirectionality { |
| 41 | + script_direction: DataPayload<ScriptDirectionV1Marker>, |
| 42 | + expander: LocaleExpander, |
| 43 | +} |
| 44 | + |
| 45 | +impl LocaleDirectionality { |
| 46 | + /// A constructor which takes a [`DataProvider`] and creates a [`LocaleDirectionality`]. |
| 47 | + /// |
| 48 | + /// [📚 Help choosing a constructor](icu_provider::constructors) |
| 49 | + /// <div class="stab unstable"> |
| 50 | + /// ⚠️ The bounds on this function may change over time, including in SemVer minor releases. |
| 51 | + /// </div> |
| 52 | + pub fn try_new_unstable<P>(provider: &P) -> Result<LocaleDirectionality, LocaleTransformError> |
| 53 | + where |
| 54 | + P: DataProvider<ScriptDirectionV1Marker> |
| 55 | + + DataProvider<LikelySubtagsForLanguageV1Marker> |
| 56 | + + DataProvider<LikelySubtagsForScriptRegionV1Marker> |
| 57 | + + ?Sized, |
| 58 | + { |
| 59 | + let expander = LocaleExpander::try_new_unstable(provider)?; |
| 60 | + Self::try_new_with_expander_unstable(provider, expander) |
| 61 | + } |
| 62 | + |
| 63 | + // Note: This is a custom impl because the bounds on `try_new_unstable` don't suffice |
| 64 | + #[doc = icu_provider::gen_any_buffer_docs!(ANY, icu_provider, Self::try_new_unstable)] |
| 65 | + pub fn try_new_with_any_provider( |
| 66 | + provider: &(impl AnyProvider + ?Sized), |
| 67 | + ) -> Result<LocaleDirectionality, LocaleTransformError> { |
| 68 | + let expander = LocaleExpander::try_new_with_any_provider(provider)?; |
| 69 | + Self::try_new_with_expander_unstable(&provider.as_downcasting(), expander) |
| 70 | + } |
| 71 | + |
| 72 | + // Note: This is a custom impl because the bounds on `try_new_unstable` don't suffice |
| 73 | + #[doc = icu_provider::gen_any_buffer_docs!(BUFFER, icu_provider, Self::try_new_unstable)] |
| 74 | + #[cfg(feature = "serde")] |
| 75 | + pub fn try_new_with_buffer_provider( |
| 76 | + provider: &(impl BufferProvider + ?Sized), |
| 77 | + ) -> Result<LocaleDirectionality, LocaleTransformError> { |
| 78 | + let expander = LocaleExpander::try_new_with_buffer_provider(provider)?; |
| 79 | + Self::try_new_with_expander_unstable(&provider.as_deserializing(), expander) |
| 80 | + } |
| 81 | + |
| 82 | + /// Creates a [`LocaleDirectionality`] with a custom [`LocaleExpander`] object. |
| 83 | + /// |
| 84 | + /// For example, use this constructor if you wish to support all languages. |
| 85 | + /// |
| 86 | + /// [📚 Help choosing a constructor](icu_provider::constructors) |
| 87 | + /// <div class="stab unstable"> |
| 88 | + /// ⚠️ The bounds on this function may change over time, including in SemVer minor releases. |
| 89 | + /// </div> |
| 90 | + /// |
| 91 | + /// # Examples |
| 92 | + /// |
| 93 | + /// ``` |
| 94 | + /// use icu_locid::locale; |
| 95 | + /// use icu_locid_transform::{Direction, LocaleDirectionality, LocaleExpander}; |
| 96 | + /// |
| 97 | + /// let ld_default = LocaleDirectionality::try_new_unstable(&icu_testdata::unstable()) |
| 98 | + /// .expect("create failed"); |
| 99 | + /// |
| 100 | + /// assert_eq!(ld_default.get(&locale!("jbn")), None); |
| 101 | + /// |
| 102 | + /// let expander = LocaleExpander::try_new_extended_unstable(&icu_testdata::unstable()) |
| 103 | + /// .expect("create failed"); |
| 104 | + /// let ld_extended = LocaleDirectionality::try_new_with_expander_unstable( |
| 105 | + /// &icu_testdata::unstable(), |
| 106 | + /// expander, |
| 107 | + /// ).expect("create failed"); |
| 108 | + /// |
| 109 | + /// assert_eq!(ld_extended.get(&locale!("jbn")), Some(Direction::RightToLeft)); |
| 110 | + /// ``` |
| 111 | + pub fn try_new_with_expander_unstable<P>( |
| 112 | + provider: &P, |
| 113 | + expander: LocaleExpander, |
| 114 | + ) -> Result<LocaleDirectionality, LocaleTransformError> |
| 115 | + where |
| 116 | + P: DataProvider<ScriptDirectionV1Marker> + ?Sized, |
| 117 | + { |
| 118 | + let script_direction = provider.load(Default::default())?.take_payload()?; |
| 119 | + |
| 120 | + Ok(LocaleDirectionality { |
| 121 | + script_direction, |
| 122 | + expander, |
| 123 | + }) |
| 124 | + } |
| 125 | + |
| 126 | + /// Returns the script direction of the given locale. |
| 127 | + /// |
| 128 | + /// Note that the direction is a property of the script of a locale, not of the language. As such, |
| 129 | + /// when given a locale without an associated script tag (i.e., `locale!("en")` vs. `locale!("en-Latn")`), |
| 130 | + /// this method first tries to infer the script using the language and region before returning its direction. |
| 131 | + /// |
| 132 | + /// If you already have a script struct and want to get its direction, you should use |
| 133 | + /// `Locale::from(Some(my_script))` and call this method. |
| 134 | + /// |
| 135 | + /// # Examples |
| 136 | + /// |
| 137 | + /// Using an existing locale: |
| 138 | + /// |
| 139 | + /// ``` |
| 140 | + /// use icu_locid::locale; |
| 141 | + /// use icu_locid_transform::{Direction, LocaleDirectionality}; |
| 142 | + /// |
| 143 | + /// let ld = LocaleDirectionality::try_new_unstable(&icu_testdata::unstable()) |
| 144 | + /// .expect("create failed"); |
| 145 | + /// |
| 146 | + /// assert_eq!(ld.get(&locale!("en-US")), Some(Direction::LeftToRight)); |
| 147 | + /// |
| 148 | + /// assert_eq!(ld.get(&locale!("ar")), Some(Direction::RightToLeft)); |
| 149 | + /// |
| 150 | + /// assert_eq!(ld.get(&locale!("foo")), None); |
| 151 | + /// ``` |
| 152 | + /// |
| 153 | + /// Using a script directly: |
| 154 | + /// |
| 155 | + /// ``` |
| 156 | + /// use icu_locid::subtags_script as script; |
| 157 | + /// use icu_locid::Locale; |
| 158 | + /// use icu_locid_transform::{Direction, LocaleDirectionality}; |
| 159 | + /// |
| 160 | + /// let ld = LocaleDirectionality::try_new_unstable(&icu_testdata::unstable()) |
| 161 | + /// .expect("create failed"); |
| 162 | + /// |
| 163 | + /// assert_eq!(ld.get(&Locale::from(Some(script!("Latn")))), Some(Direction::LeftToRight)); |
| 164 | + /// ``` |
| 165 | + pub fn get(&self, locale: &Locale) -> Option<Direction> { |
| 166 | + let script = self.expander.get_likely_script(&locale.id)?; |
| 167 | + |
| 168 | + if self.script_in_ltr(script) { |
| 169 | + Some(Direction::LeftToRight) |
| 170 | + } else if self.script_in_rtl(script) { |
| 171 | + Some(Direction::RightToLeft) |
| 172 | + } else { |
| 173 | + None |
| 174 | + } |
| 175 | + } |
| 176 | + |
| 177 | + /// Returns true if the given locale is right-to-left. |
| 178 | + /// |
| 179 | + /// Note that if this method returns `false`, it does not mean that the locale is left-to-right. |
| 180 | + /// You should use `LocaleDirectionality::get` if you need to differentiate between these cases. |
| 181 | + /// |
| 182 | + /// See [`LocaleDirectionality::get`] for more information. |
| 183 | + pub fn is_right_to_left(&self, locale: &Locale) -> bool { |
| 184 | + self.expander |
| 185 | + .get_likely_script(&locale.id) |
| 186 | + .map(|s| self.script_in_rtl(s)) |
| 187 | + .unwrap_or(false) |
| 188 | + } |
| 189 | + |
| 190 | + /// Returns true if the given locale is left-to-right. |
| 191 | + /// |
| 192 | + /// Note that if this method returns `false`, it does not mean that the locale is right-to-left. |
| 193 | + /// You should use `LocaleDirectionality::get` if you need to differentiate between these cases. |
| 194 | + /// |
| 195 | + /// See [`LocaleDirectionality::get`] for more information. |
| 196 | + pub fn is_left_to_right(&self, locale: &Locale) -> bool { |
| 197 | + self.expander |
| 198 | + .get_likely_script(&locale.id) |
| 199 | + .map(|s| self.script_in_ltr(s)) |
| 200 | + .unwrap_or(false) |
| 201 | + } |
| 202 | + |
| 203 | + fn script_in_rtl(&self, script: Script) -> bool { |
| 204 | + self.script_direction |
| 205 | + .get() |
| 206 | + .rtl |
| 207 | + .binary_search(&script.into_tinystr().to_unvalidated()) |
| 208 | + .is_ok() |
| 209 | + } |
| 210 | + |
| 211 | + fn script_in_ltr(&self, script: Script) -> bool { |
| 212 | + self.script_direction |
| 213 | + .get() |
| 214 | + .ltr |
| 215 | + .binary_search(&script.into_tinystr().to_unvalidated()) |
| 216 | + .is_ok() |
| 217 | + } |
| 218 | +} |
0 commit comments