diff --git a/components/locid_transform/src/canonicalizer.rs b/components/locid_transform/src/canonicalizer.rs index cbbb92e1449..5a3782638a1 100644 --- a/components/locid_transform/src/canonicalizer.rs +++ b/components/locid_transform/src/canonicalizer.rs @@ -20,11 +20,7 @@ use icu_locid::{ use icu_provider::prelude::*; use tinystr::TinyAsciiStr; -/// The LocaleCanonicalizer provides methods to canonicalize Locales and -/// LanguageIdentifiers based upon [`CLDR`] data. -/// -/// It currently supports locale canonicalization based upon the canonicalization -/// algorithm from [`UTS #35: Unicode LDML 3. LocaleId Canonicalization`]. +/// Implements the algorithm defined in *[UTS #35: Annex C, LocaleId Canonicalization]*. /// /// # Examples /// @@ -39,9 +35,7 @@ use tinystr::TinyAsciiStr; /// assert_eq!(locale, "ja-Latn-alalc97-fonipa".parse().unwrap()); /// ``` /// -/// [`ICU4X`]: ../icu/index.html -/// [`CLDR`]: http://cldr.unicode.org/ -/// [`UTS #35: Unicode LDML 3. LocaleId Canonicalization`]: http://unicode.org/reports/tr35/#LocaleId_Canonicalization, +/// [UTS #35: Annex C, LocaleId Canonicalization]: http://unicode.org/reports/tr35/#LocaleId_Canonicalization #[derive(Debug)] pub struct LocaleCanonicalizer { /// Data to support canonicalization. diff --git a/components/locid_transform/src/directionality.rs b/components/locid_transform/src/directionality.rs index 67bacb3947b..8a6c243b81b 100644 --- a/components/locid_transform/src/directionality.rs +++ b/components/locid_transform/src/directionality.rs @@ -20,8 +20,7 @@ pub enum Direction { RightToLeft, } -/// The `LocaleDirectionality` provides methods to determine the direction of a locale based -/// on [`CLDR`] data. +/// Provides methods to determine the direction of a locale. /// /// # Examples /// @@ -33,8 +32,6 @@ pub enum Direction { /// /// assert_eq!(ld.get(&locale!("en")), Some(Direction::LeftToRight)); /// ``` -/// -/// [`CLDR`]: http://cldr.unicode.org/ #[derive(Debug)] pub struct LocaleDirectionality { script_direction: DataPayload, diff --git a/components/locid_transform/src/expander.rs b/components/locid_transform/src/expander.rs index ead15fff1c9..56f204c324d 100644 --- a/components/locid_transform/src/expander.rs +++ b/components/locid_transform/src/expander.rs @@ -11,15 +11,8 @@ use icu_provider::prelude::*; use crate::TransformResult; -/// LocaleExpander supports the `minimize` and `maximize` likely subtags -/// algorithms as described in [`UTS #35: Unicode LDML 3. Likely Subtags`]. -/// -/// The maximize method potentially updates a passed in locale in place -/// depending up the results of running the 'Add Likely Subtags' algorithm -/// from [`UTS #35: Unicode LDML 3. Likely Subtags`]. -/// -/// This minimize method returns a new Locale that is the result of running the -/// 'Remove Likely Subtags' algorithm from [`UTS #35: Unicode LDML 3. Likely Subtags`]. +/// Implements the *Add Likely Subtags* and *Remove Likely Subtags* +/// algorithms as defined in *[UTS #35: Likely Subtags]*. /// /// # Examples /// @@ -71,8 +64,7 @@ use crate::TransformResult; /// assert_eq!(locale, locale!("atj-Latn-CA")); /// ``` /// -/// [`CLDR`]: http://cldr.unicode.org/ -/// [`UTS #35: Unicode LDML 3. Likely Subtags`]: https://www.unicode.org/reports/tr35/#Likely_Subtags. +/// [UTS #35: Likely Subtags]: https://www.unicode.org/reports/tr35/#Likely_Subtags #[derive(Debug, Clone)] pub struct LocaleExpander { likely_subtags_l: DataPayload, diff --git a/components/locid_transform/src/fallback/mod.rs b/components/locid_transform/src/fallback/mod.rs index db92dff3388..6b13e020143 100644 --- a/components/locid_transform/src/fallback/mod.rs +++ b/components/locid_transform/src/fallback/mod.rs @@ -14,7 +14,7 @@ //! //! ``` //! use icu_locid::locale; -//! use icu_locid_transform::fallback::LocaleFallbacker; +//! use icu_locid_transform::LocaleFallbacker; //! //! // Set up a LocaleFallbacker with data. //! let fallbacker = LocaleFallbacker::new(); @@ -49,9 +49,44 @@ pub use icu_provider::fallback::*; mod algorithms; -/// Entry type for locale fallbacking. +/// Implements the algorithm defined in *[UTS #35: Locale Inheritance and Matching]*. /// -/// See the module-level documentation for an example. +/// Note that this implementation performs some additional steps compared to the *UTS #35* +/// algorithm, see *[the design doc]* for a detailed description, and [#2243]( +/// https://github.com/unicode-org/icu4x/issues/2243) to track aligment with *UTS #35*. +/// +/// # Examples +/// +/// ``` +/// use icu_locid::locale; +/// use icu_locid_transform::fallback::LocaleFallbacker; +/// +/// // Set up a LocaleFallbacker with data. +/// let fallbacker = LocaleFallbacker::new(); +/// +/// // Create a LocaleFallbackerIterator with a default configuration. +/// // By default, uses language priority with no additional extension keywords. +/// let mut fallback_iterator = fallbacker +/// .for_config(Default::default()) +/// .fallback_for(locale!("hi-Latn-IN").into()); +/// +/// // Run the algorithm and check the results. +/// assert_eq!(fallback_iterator.get(), &locale!("hi-Latn-IN").into()); +/// fallback_iterator.step(); +/// assert_eq!(fallback_iterator.get(), &locale!("hi-Latn").into()); +/// fallback_iterator.step(); +/// assert_eq!(fallback_iterator.get(), &locale!("en-IN").into()); +/// fallback_iterator.step(); +/// assert_eq!(fallback_iterator.get(), &locale!("en-001").into()); +/// fallback_iterator.step(); +/// assert_eq!(fallback_iterator.get(), &locale!("en").into()); +/// fallback_iterator.step(); +/// assert_eq!(fallback_iterator.get(), &locale!("und").into()); +/// ``` +/// +/// [UTS #35: Locale Inheritance and Matching]: https://www.unicode.org/reports/tr35/#Locale_Inheritance +/// [the design doc]: https://docs.google.com/document/d/1Mp7EUyl-sFh_HZYgyeVwj88vJGpCBIWxzlCwGgLCDwM/edit +#[doc(hidden)] #[derive(Debug, Clone, PartialEq)] pub struct LocaleFallbacker { likely_subtags: DataPayload, diff --git a/components/locid_transform/src/lib.rs b/components/locid_transform/src/lib.rs index a6aa4cf2bb8..4c4e34aeae2 100644 --- a/components/locid_transform/src/lib.rs +++ b/components/locid_transform/src/lib.rs @@ -99,6 +99,8 @@ pub use canonicalizer::LocaleCanonicalizer; pub use directionality::{Direction, LocaleDirectionality}; pub use error::LocaleTransformError; pub use expander::LocaleExpander; +#[doc(inline)] +pub use fallback::LocaleFallbacker; /// Used to track the result of a transformation operation that potentially modifies its argument in place. #[derive(Debug, PartialEq)] diff --git a/ffi/diplomat/src/fallbacker.rs b/ffi/diplomat/src/fallbacker.rs index d616d503684..b3f21b7530a 100644 --- a/ffi/diplomat/src/fallbacker.rs +++ b/ffi/diplomat/src/fallbacker.rs @@ -8,8 +8,8 @@ pub mod ffi { use icu_locid_transform::fallback::LocaleFallbackConfig; use icu_locid_transform::fallback::LocaleFallbackIterator; use icu_locid_transform::fallback::LocaleFallbackPriority; - use icu_locid_transform::fallback::LocaleFallbacker; use icu_locid_transform::fallback::LocaleFallbackerWithConfig; + use icu_locid_transform::LocaleFallbacker; use crate::{ errors::ffi::ICU4XError, locale::ffi::ICU4XLocale, provider::ffi::ICU4XDataProvider, diff --git a/provider/adapters/src/fallback/mod.rs b/provider/adapters/src/fallback/mod.rs index be5e79a524f..c0a05d14ec2 100644 --- a/provider/adapters/src/fallback/mod.rs +++ b/provider/adapters/src/fallback/mod.rs @@ -126,7 +126,7 @@ impl

LocaleFallbackProvider

{ /// /// ``` /// use icu_locid::locale; - /// use icu_locid_transform::fallback::LocaleFallbacker; + /// use icu_locid_transform::LocaleFallbacker; /// use icu_provider::hello_world::*; /// use icu_provider::prelude::*; /// use icu_provider_adapters::fallback::LocaleFallbackProvider; diff --git a/provider/core/src/fallback.rs b/provider/core/src/fallback.rs index c1cb4f6c37a..5c4e13b8da6 100644 --- a/provider/core/src/fallback.rs +++ b/provider/core/src/fallback.rs @@ -65,7 +65,7 @@ pub struct LocaleFallbackConfig { /// use icu_locid::locale; /// use icu_locid_transform::fallback::LocaleFallbackConfig; /// use icu_locid_transform::fallback::LocaleFallbackPriority; - /// use icu_locid_transform::fallback::LocaleFallbacker; + /// use icu_locid_transform::LocaleFallbacker; /// /// // Set up the fallback iterator. /// let fallbacker = LocaleFallbacker::new(); @@ -93,7 +93,7 @@ pub struct LocaleFallbackConfig { /// use icu_locid::locale; /// use icu_locid_transform::fallback::LocaleFallbackConfig; /// use icu_locid_transform::fallback::LocaleFallbackPriority; - /// use icu_locid_transform::fallback::LocaleFallbacker; + /// use icu_locid_transform::LocaleFallbacker; /// /// // Set up the fallback iterator. /// let fallbacker = LocaleFallbacker::new(); @@ -122,7 +122,7 @@ pub struct LocaleFallbackConfig { /// ``` /// use icu_locid::locale; /// use icu_locid_transform::fallback::LocaleFallbackConfig; - /// use icu_locid_transform::fallback::LocaleFallbacker; + /// use icu_locid_transform::LocaleFallbacker; /// /// // Set up the fallback iterator. /// let fallbacker = LocaleFallbacker::new(); @@ -159,7 +159,7 @@ pub struct LocaleFallbackConfig { /// use icu_locid_transform::fallback::LocaleFallbackConfig; /// use icu_locid_transform::fallback::LocaleFallbackPriority; /// use icu_locid_transform::fallback::LocaleFallbackSupplement; - /// use icu_locid_transform::fallback::LocaleFallbacker; + /// use icu_locid_transform::LocaleFallbacker; /// /// // Set up the fallback iterator. /// let fallbacker = LocaleFallbacker::new(); diff --git a/provider/datagen/src/driver.rs b/provider/datagen/src/driver.rs index 91e6d1b7218..78faac91c61 100644 --- a/provider/datagen/src/driver.rs +++ b/provider/datagen/src/driver.rs @@ -7,7 +7,7 @@ use crate::FallbackMode; use icu_locid::extensions::unicode::key; use icu_locid::LanguageIdentifier; use icu_locid_transform::fallback::LocaleFallbackIterator; -use icu_locid_transform::fallback::LocaleFallbacker; +use icu_locid_transform::LocaleFallbacker; use icu_provider::datagen::*; use icu_provider::prelude::*; use once_cell::sync::Lazy;