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 //! Canonicalization of locale identifiers based on [`CLDR`] data. 6 //! 7 //! This module is published as its own crate ([`icu_locale`](https://docs.rs/icu_locale/latest/icu_locale/)) 8 //! and as part of the [`icu`](https://docs.rs/icu/latest/icu/) crate. See the latter for more details on the ICU4X project. 9 //! 10 //! It currently supports locale canonicalization based upon the canonicalization 11 //! algorithm from [`UTS #35: Unicode LDML 3. LocaleId Canonicalization`], 12 //! as well as the minimize and maximize likely subtags algorithms 13 //! as described in [`UTS #35: Unicode LDML 3. Likely Subtags`]. 14 //! 15 //! The maximize method potentially updates a passed in locale in place 16 //! depending up the results of running the 'Add Likely Subtags' algorithm 17 //! from [`UTS #35: Unicode LDML 3. Likely Subtags`]. 18 //! 19 //! This minimize method returns a new Locale that is the result of running the 20 //! 'Remove Likely Subtags' algorithm from [`UTS #35: Unicode LDML 3. Likely Subtags`]. 21 //! 22 //! # Examples 23 //! 24 //! ``` 25 //! use icu::locale::Locale; 26 //! use icu::locale::{LocaleCanonicalizer, TransformResult}; 27 //! 28 //! let lc = LocaleCanonicalizer::new_extended(); 29 //! 30 //! let mut locale: Locale = "ja-Latn-fonipa-hepburn-heploc" 31 //! .parse() 32 //! .expect("parse failed"); 33 //! assert_eq!(lc.canonicalize(&mut locale), TransformResult::Modified); 34 //! assert_eq!(locale, "ja-Latn-alalc97-fonipa".parse::<Locale>().unwrap()); 35 //! ``` 36 //! 37 //! ``` 38 //! use icu::locale::{locale, LocaleExpander, TransformResult}; 39 //! 40 //! let lc = LocaleExpander::new_common(); 41 //! 42 //! let mut locale = locale!("zh-CN"); 43 //! assert_eq!(lc.maximize(&mut locale.id), TransformResult::Modified); 44 //! assert_eq!(locale, locale!("zh-Hans-CN")); 45 //! 46 //! let mut locale = locale!("zh-Hant-TW"); 47 //! assert_eq!(lc.maximize(&mut locale.id), TransformResult::Unmodified); 48 //! assert_eq!(locale, locale!("zh-Hant-TW")); 49 //! ``` 50 //! 51 //! ``` 52 //! use icu::locale::{locale, LocaleExpander, TransformResult}; 53 //! use writeable::assert_writeable_eq; 54 //! 55 //! let lc = LocaleExpander::new_common(); 56 //! 57 //! let mut locale = locale!("zh-Hans-CN"); 58 //! assert_eq!(lc.minimize(&mut locale.id), TransformResult::Modified); 59 //! assert_eq!(locale, locale!("zh")); 60 //! 61 //! let mut locale = locale!("zh"); 62 //! assert_eq!(lc.minimize(&mut locale.id), TransformResult::Unmodified); 63 //! assert_eq!(locale, locale!("zh")); 64 //! ``` 65 //! 66 //! [`ICU4X`]: ../icu/index.html 67 //! [`CLDR`]: http://cldr.unicode.org/ 68 //! [`UTS #35: Unicode LDML 3. Likely Subtags`]: https://www.unicode.org/reports/tr35/#Likely_Subtags. 69 //! [`UTS #35: Unicode LDML 3. LocaleId Canonicalization`]: http://unicode.org/reports/tr35/#LocaleId_Canonicalization, 70 71 // https://github.com/unicode-org/icu4x/blob/main/documents/process/boilerplate.md#library-annotations 72 #![cfg_attr(not(any(test, doc)), no_std)] 73 #![cfg_attr( 74 not(test), 75 deny( 76 clippy::indexing_slicing, 77 clippy::unwrap_used, 78 clippy::expect_used, 79 clippy::panic, 80 clippy::exhaustive_structs, 81 clippy::exhaustive_enums, 82 clippy::trivially_copy_pass_by_ref, 83 missing_debug_implementations, 84 ) 85 )] 86 #![warn(missing_docs)] 87 88 extern crate alloc; 89 90 mod canonicalizer; 91 mod directionality; 92 pub mod exemplar_chars; 93 mod expander; 94 pub mod fallback; 95 pub mod provider; 96 97 pub use icu_locale_core::*; 98 99 pub use canonicalizer::LocaleCanonicalizer; 100 pub use directionality::{Direction, LocaleDirectionality}; 101 pub use expander::LocaleExpander; 102 #[doc(inline)] 103 pub use fallback::LocaleFallbacker; 104 105 /// Used to track the result of a transformation operation that potentially modifies its argument in place. 106 #[derive(Debug, PartialEq)] 107 #[allow(clippy::exhaustive_enums)] // this enum is stable 108 pub enum TransformResult { 109 /// The canonicalization operation modified the locale. 110 Modified, 111 /// The canonicalization operation did not modify the locale. 112 Unmodified, 113 } 114