vendor/icu_locid/src/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_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::subtags::{Language, Region};
  26 //! use icu::locid::Locale;
  27 //!
  28 //! let mut loc: Locale = "en-US".parse().expect("Parsing failed.");
  29 //!
  30 //! let lang: Language = "en".parse().expect("Parsing failed.");
  31 //! let region: Region = "US".parse().expect("Parsing failed.");
  32 //!
  33 //! assert_eq!(loc.id.language, lang);
  34 //! assert_eq!(loc.id.script, None);
  35 //! assert_eq!(loc.id.region, Some(region));
  36 //! assert_eq!(loc.id.variants.len(), 0);
  37 //!
  38 //! let region: Region = "GB".parse().expect("Parsing failed.");
  39 //! loc.id.region = Some(region);
  40 //!
  41 //! assert_eq!(loc.to_string(), "en-GB");
  42 //! ```
  43 //!
  44 //! ## Macros
  45 //!
  46 //! ```rust
  47 //! use icu::locid::{
  48 //!     langid, subtags_language as language, subtags_region as region,
  49 //! };
  50 //!
  51 //! let lid = langid!("EN_US");
  52 //!
  53 //! assert_eq!(lid.language, language!("en"));
  54 //! assert_eq!(lid.region, Some(region!("US")));
  55 //! ```
  56
  57 //!
  58 //! For more details, see [`Locale`] and [`LanguageIdentifier`].
  59 //!
  60 //! [`UTS #35: Unicode LDML 3. Unicode Language and Locale Identifiers`]: https://unicode.org/reports/tr35/tr35.html#Unicode_Language_and_Locale_Identifiers
  61 //! [`ICU4X`]: ../icu/index.html
  62 //! [`Unicode Extensions`]: extensions
  63
  64 // https://github.com/unicode-org/icu4x/blob/main/docs/process/boilerplate.md#library-annotations
  65 #![cfg_attr(not(any(test, feature = "std")), no_std)]
  66 #![cfg_attr(
  67     not(test),
  68     deny(
  69         clippy::indexing_slicing,
  70         clippy::unwrap_used,
  71         clippy::expect_used,
  72         clippy::panic,
  73         clippy::exhaustive_structs,
  74         clippy::exhaustive_enums,
  75         // TODO(#2266): enable missing_debug_implementations,
  76     )
  77 )]
  78 #![warn(missing_docs)]
  79
  80 extern crate alloc;
  81
  82 #[macro_use]
  83 mod helpers;
  84
  85 mod langid;
  86 mod locale;
  87 mod macros;
  88 mod ordering;
  89 mod parser;
  90
  91 pub use langid::LanguageIdentifier;
  92 pub use locale::Locale;
  93 pub use ordering::SubtagOrderingResult;
  94 pub use parser::errors::ParserError;
  95
  96 pub mod extensions;
  97 pub mod subtags;
  98 pub mod zerovec;
  99
 100 #[cfg(feature = "serde")]
 101 mod serde;