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//! Parsing, manipulating, and serializing Unicode Language and Locale Identifiers.
6//!
7//! This module is published as its own crate ([`icu_locid`](https://docs.rs/icu_locid/latest/icu_locid/))
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//! The module provides algorithms for parsing a string into a well-formed language or locale identifier
11//! as defined by [`UTS #35: Unicode LDML 3. Unicode Language and Locale Identifiers`].
12//!
13//! [`Locale`] is the most common structure to use for storing information about a language,
14//! script, region, variants and extensions. In almost all cases, this struct should be used as the
15//! base unit for all locale management operations.
16//!
17//! [`LanguageIdentifier`] is a strict subset of [`Locale`] which can be useful in a narrow range of
18//! cases where [`Unicode Extensions`] are not relevant.
19//!
20//! If in doubt, use [`Locale`].
21//!
22//! # Examples
23//!
24//! ```
25//! use icu::locid::Locale;
26//! use icu::locid::{
27//! locale,
28//! subtags::{language, region},
29//! };
30//!
31//! let mut loc: Locale = locale!("en-US");
32//!
33//! assert_eq!(loc.id.language, language!("en"));
34//! assert_eq!(loc.id.script, None);
35//! assert_eq!(loc.id.region, Some(region!("US")));
36//! assert_eq!(loc.id.variants.len(), 0);
37//!
38//! loc.id.region = Some(region!("GB"));
39//!
40//! assert_eq!(loc, locale!("en-GB"));
41//! ```
42//!
43//! For more details, see [`Locale`] and [`LanguageIdentifier`].
44//!
45//! [`UTS #35: Unicode LDML 3. Unicode Language and Locale Identifiers`]: https://unicode.org/reports/tr35/tr35.html#Unicode_Language_and_Locale_Identifiers
46//! [`ICU4X`]: ../icu/index.html
47//! [`Unicode Extensions`]: extensions
48
49// https://github.com/unicode-org/icu4x/blob/main/documents/process/boilerplate.md#library-annotations
50#![cfg_attr(not(any(test, feature = "std")), no_std)]
51#![cfg_attr(
52 not(test),
53 deny(
54 clippy::indexing_slicing,
55 clippy::unwrap_used,
56 clippy::expect_used,
57 clippy::panic,
58 clippy::exhaustive_structs,
59 clippy::exhaustive_enums,
60 missing_debug_implementations,
61 )
62)]
63#![warn(missing_docs)]
64
65extern crate alloc;
66
67#[macro_use]
68mod helpers;
69
70mod langid;
71mod locale;
72mod macros;
73mod ordering;
74mod parser;
75mod shortvec;
76
77pub use langid::LanguageIdentifier;
78pub use locale::Locale;
79#[allow(deprecated)]
80pub use ordering::SubtagOrderingResult;
81pub use parser::errors::ParserError;
82
83#[doc(no_inline)]
84pub use ParserError as Error;
85
86pub mod extensions;
87#[macro_use]
88pub mod subtags;
89pub mod zerovec;
90
91#[cfg(feature = "serde")]
92mod serde;
93
94#[cfg(feature = "databake")]
95mod databake;
96