1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185

// This file is part of ICU4X. For terms of use, please see the file
// called LICENSE at the top level of the ICU4X source tree
// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ).

//! `icu` is the main meta-crate of the `ICU4X` project.
//!
//! It provides a comprehensive selection of functionality found in
//! [International Components for Unicode](http://icu.unicode.org/)
//! in their canonical configurations intended to enable software
//! internationalization capabilities.
//!
//! This crate exists to collect the most important functionality for users
//! together in one place.
//! It does not bring any unique functionality, but rather,
//! it re-exports the relevant crates as modules.
//! The exported crate corresponding to each module is also
//! available in a stand-alone manner, i.e. `icu::list` as `icu_list`.
//!
//! # Data Management
//!
//! Most functionality relies on data which clients have to provide to the APIs.
//!
//! `ICU4X` uses the concept of a [`DataProvider`] to separate data from logic.
//! Data providers come in many different forms; the following providers are provided
//! by `ICU4X` in separate crates:
//! * [`BlobDataProvider`]: uses an in-memory serde-serialized blob. This is the most flexible provider, and
//!   data can be updated at runtime.
//! * `BakedDataProvider`: a code-generated provider that contains the data directly in Rust code. This is
//!   the most efficient provider as it's serialization-free, and allows for compile-time optimizations.
//! * [`FsDataProvider`]: uses a file system tree of Serde files. This is mostly useful for development and
//!   not recommended in production for performance reasons.
//! * [`icu_provider_adapters`]: this crate contains APIs to combine providers or
//!   provide additional functionality such as locale fallback.
//!
//! The data that is required by these providers (in `BakedDataProvider`'s case, the provider itself) can be
//! generated and customized using the [`icu_datagen`] crate.
//!
//! The following example uses the [`icu_testdata`] crate, which contains prepackaged data providers
//! for a small set of locales.
//!
//! # Example
//!
//! ```
//! use icu::calendar::DateTime;
//! use icu::datetime::{options::length, DateTimeFormatter};
//! use icu::locid::locale;
//! use writeable::assert_writeable_eq;
//!
//! let options = length::Bag::from_date_time_style(
//!     length::Date::Long,
//!     length::Time::Medium,
//! )
//! .into();
//!
//! let dtf = DateTimeFormatter::try_new_unstable(
//!     &icu_testdata::unstable(),
//!     &locale!("es").into(),
//!     options,
//! )
//! .expect("Failed to create DateTimeFormatter instance.");
//!
//! let date = DateTime::try_new_iso_datetime(2020, 9, 12, 12, 35, 0)
//!     .expect("Failed to parse date.");
//! let date = date.to_any();
//!
//! let formatted_date = dtf.format(&date).expect("Formatting failed");
//! assert_writeable_eq!(formatted_date, "12 de septiembre de 2020, 12:35:00");
//!
//! let formatted_date_string =
//!     dtf.format_to_string(&date).expect("Formatting failed");
//! assert_eq!(formatted_date_string, "12 de septiembre de 2020, 12:35:00");
//! ```
//!
//! # Features
//!
//! ICU4X components share a set of common Cargo features that control whether core pieces of
//! functionality are compiled. These features are:
//!
//! - `std`: Whether to include `std` support. Without this Cargo feature, `icu` is `#[no_std]`-compatible
//! - `serde`: Whether to include `serde::Deserialize` implementations for data structs, such as [`SymbolsV1`],
//!   and `serde::{Serialize, Deserialize}` implementations for core library types, such as [`Locale`]. These are
//!   required with `serde`-backed providers like [`BlobDataProvider`][^1].
//! - `experimental`: Whether to enable experimental preview features. Modules enabled with
//!   this feature may not be production-ready and could change at any time.
//!
//! The following Cargo features are only available on the individual crates, but not on this meta-crate:
//!
//! - `datagen`: Whether to implement `serde::Serialize` and functionality that is only required during data generation.
//! - `bench`: Whether to enable exhaustive benchmarks. This can be enabled on individual crates
//!   when running `cargo bench`.
//!
//! There are additional features that, when enabled on specific crates, enable functionality across ICU4X:
//!
//! - `icu_provider/sync`: makes [`DataPayload`] implement `Send + Sync`, which in turn
//!   makes most ICU4X objects also implement `Send + Sync`.
//! - `icu_provider/deserialize_*`: enables ICU4X buffer providers to read various different
//!   serialization formats. See [`BufferProvider`](icu_provider::BufferProvider) for details.
//!
//! [^1]: If using blob data, you need to enable one of the deserialization Cargo features on the `icu_provider` crate, as noted above.
//!
//!
//! [`DataProvider`]: icu_provider::DataProvider
//! [`DataPayload`]: icu_provider::DataPayload
//! [`FsDataProvider`]: https://docs.rs/icu_provider_fs/latest/icu_provider_fs/struct.FsDataProvider.html
//! [`BlobDataProvider`]: https://docs.rs/icu_provider_blob/latest/icu_provider_blob/struct.BlobDataProvider.html
//! [`icu_testdata`]: https://docs.rs/icu_testdata/latest/icu_testdata/
//! [`icu_provider_adapters`]: https://docs.rs/icu_provider_adapters/latest/icu_provider_adapters/
//! [`icu_datagen`]: https://docs.rs/icu_datagen/latest/icu_datagen/
//! [`Locale`]: crate::locid::Locale
//! [`SymbolsV1`]: crate::decimal::provider::DecimalSymbolsV1

// https://github.com/unicode-org/icu4x/blob/main/docs/process/boilerplate.md#library-annotations
#![cfg_attr(not(any(test, feature = "std")), no_std)]
#![cfg_attr(
    not(test),
    deny(
        clippy::indexing_slicing,
        clippy::unwrap_used,
        clippy::expect_used,
        clippy::panic,
        clippy::exhaustive_structs,
        clippy::exhaustive_enums,
        missing_debug_implementations,
    )
)]
#![warn(missing_docs)]

#[cfg(doc)]
// Needed for intra-doc link to work, since icu_provider is otherwise never mentioned in this crate
extern crate icu_provider;

#[doc(inline)]
pub use icu_calendar as calendar;

#[cfg(feature = "icu_casemapping")]
#[doc(inline)]
pub use icu_casemapping as casemapping;

#[doc(inline)]
pub use icu_collator as collator;

#[doc(inline)]
pub use icu_datetime as datetime;

#[doc(inline)]
pub use icu_decimal as decimal;

#[doc(inline)]
pub use icu_list as list;

#[doc(inline)]
pub use icu_locid_transform as locid_transform;

#[doc(inline)]
pub use icu_locid as locid;

#[doc(inline)]
pub use icu_normalizer as normalizer;

#[doc(inline)]
pub use icu_plurals as plurals;

#[doc(inline)]
pub use icu_properties as properties;

#[doc(inline)]
pub use icu_collections as collections;

#[doc(inline)]
pub use icu_segmenter as segmenter;

#[doc(inline)]
pub use icu_timezone as timezone;

#[cfg(feature = "icu_displaynames")]
#[doc(inline)]
pub use icu_displaynames as displaynames;

#[cfg(feature = "icu_relativetime")]
#[doc(inline)]
pub use icu_relativetime as relativetime;

#[cfg(feature = "icu_compactdecimal")]
#[doc(inline)]
pub use icu_compactdecimal as compactdecimal;