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