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_locid_transform`](https://docs.rs/icu_locid_transform/latest/icu_locid_transform/))
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::locid::Locale;
26//! use icu::locid_transform::{LocaleCanonicalizer, TransformResult};
27//!
28//! let lc = LocaleCanonicalizer::new();
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::locid::locale;
39//! use icu::locid_transform::{LocaleExpander, TransformResult};
40//!
41//! let lc = LocaleExpander::new();
42//!
43//! let mut locale = locale!("zh-CN");
44//! assert_eq!(lc.maximize(&mut locale), TransformResult::Modified);
45//! assert_eq!(locale, locale!("zh-Hans-CN"));
46//!
47//! let mut locale = locale!("zh-Hant-TW");
48//! assert_eq!(lc.maximize(&mut locale), TransformResult::Unmodified);
49//! assert_eq!(locale, locale!("zh-Hant-TW"));
50//! ```
51//!
52//! ```
53//! use icu::locid::locale;
54//! use icu::locid_transform::{LocaleExpander, TransformResult};
55//! use writeable::assert_writeable_eq;
56//!
57//! let lc = LocaleExpander::new();
58//!
59//! let mut locale = locale!("zh-Hans-CN");
60//! assert_eq!(lc.minimize(&mut locale), TransformResult::Modified);
61//! assert_eq!(locale, locale!("zh"));
62//!
63//! let mut locale = locale!("zh");
64//! assert_eq!(lc.minimize(&mut locale), TransformResult::Unmodified);
65//! assert_eq!(locale, locale!("zh"));
66//! ```
67//!
68//! [`ICU4X`]: ../icu/index.html
69//! [`CLDR`]: http://cldr.unicode.org/
70//! [`UTS #35: Unicode LDML 3. Likely Subtags`]: https://www.unicode.org/reports/tr35/#Likely_Subtags.
71//! [`UTS #35: Unicode LDML 3. LocaleId Canonicalization`]: http://unicode.org/reports/tr35/#LocaleId_Canonicalization,
72
73// https://github.com/unicode-org/icu4x/blob/main/documents/process/boilerplate.md#library-annotations
74#![cfg_attr(not(any(test, feature = "std")), no_std)]
75#![cfg_attr(
76 not(test),
77 deny(
78 clippy::indexing_slicing,
79 clippy::unwrap_used,
80 clippy::expect_used,
81 clippy::panic,
82 clippy::exhaustive_structs,
83 clippy::exhaustive_enums,
84 missing_debug_implementations,
85 )
86)]
87#![warn(missing_docs)]
88
89extern crate alloc;
90
91mod canonicalizer;
92mod directionality;
93mod error;
94mod expander;
95pub mod fallback;
96pub mod provider;
97
98pub use canonicalizer::LocaleCanonicalizer;
99pub use directionality::{Direction, LocaleDirectionality};
100pub use error::LocaleTransformError;
101pub use expander::LocaleExpander;
102#[doc(inline)]
103pub 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
108pub enum TransformResult {
109 /// The canonicalization operation modified the locale.
110 Modified,
111 /// The canonicalization operation did not modify the locale.
112 Unmodified,
113}
114
115#[doc(no_inline)]
116pub use LocaleTransformError as Error;
117