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//! Formatting lists in a locale-sensitive way.
6//!
7//! This module is published as its own crate ([`icu_list`](https://docs.rs/icu_list/latest/icu_list/))
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//! # Examples
11//!
12//! ## Formatting *and* lists in Spanish
13//!
14//! ```
15//! # use icu::list::{ListFormatter, ListLength};
16//! # use icu::locid::locale;
17//! # use writeable::*;
18//! #
19//! let list_formatter = ListFormatter::try_new_and_with_length(
20//! &locale!("es").into(),
21//! ListLength::Wide,
22//! )
23//! .expect("locale should be present");
24//!
25//! assert_writeable_eq!(
26//! list_formatter.format(["España", "Suiza"].iter()),
27//! "España y Suiza",
28//! );
29//!
30//! // The Spanish 'y' sometimes becomes an 'e':
31//! assert_writeable_eq!(
32//! list_formatter.format(["España", "Suiza", "Italia"].iter()),
33//! "España, Suiza e Italia",
34//! );
35//! ```
36//!
37//! ## Formatting *or* lists in Thai
38//!
39//! ```
40//! # use icu::list::{ListFormatter, ListLength};
41//! # use icu::locid::locale;
42//! # use writeable::*;
43//! #
44//! let list_formatter = ListFormatter::try_new_or_with_length(
45//! &locale!("th").into(),
46//! ListLength::Short,
47//! )
48//! .expect("locale should be present");
49//!
50//! // We can use any Writeables as inputs
51//! assert_writeable_eq!(list_formatter.format(1..=3), "1, 2 หรือ 3",);
52//! ```
53//!
54//! ## Formatting unit lists in English
55//!
56//! ```
57//! # use icu::list::{ListFormatter, ListLength};
58//! # use icu::locid::locale;
59//! # use writeable::*;
60//! #
61//! let list_formatter = ListFormatter::try_new_unit_with_length(
62//! &locale!("en").into(),
63//! ListLength::Wide,
64//! )
65//! .expect("locale should be present");
66//!
67//! assert_writeable_eq!(
68//! list_formatter.format(["1ft", "2in"].iter()),
69//! "1ft, 2in",
70//! );
71//! ```
72//! Note: this last example is not fully internationalized. See [icu4x/2192](https://github.com/unicode-org/icu4x/issues/2192)
73//! for full unit handling.
74
75#![cfg_attr(not(feature = "std"), no_std)]
76#![cfg_attr(
77 not(test),
78 deny(
79 clippy::indexing_slicing,
80 clippy::unwrap_used,
81 clippy::expect_used,
82 clippy::panic,
83 clippy::exhaustive_structs,
84 clippy::exhaustive_enums,
85 missing_debug_implementations,
86 )
87)]
88#![warn(missing_docs)]
89
90extern crate alloc;
91
92mod error;
93mod lazy_automaton;
94mod list_formatter;
95mod patterns;
96
97pub mod provider;
98
99pub use list_formatter::*;
100
101pub use error::ListError;
102
103#[doc(no_inline)]
104pub use ListError as Error;
105
106/// Represents the style of a list. See the
107/// [CLDR spec](https://unicode.org/reports/tr35/tr35-general.html#ListPatterns)
108/// for an explanation of the different styles.
109#[derive(Copy, Clone, PartialEq, Eq, Debug, Hash, Default)]
110#[non_exhaustive]
111pub enum ListLength {
112 /// A typical list
113 #[default]
114 Wide,
115 /// A shorter list
116 Short,
117 /// The shortest type of list
118 Narrow,
119 // *Important*: When adding a variant here, make sure the code in
120 // ListFormatterPatterns::{start, middle, end, pair} stays panic-free!
121}
122