Crate icu_providersource ·
icu_provider is one of the
Unicode’s experience with ICU4X’s parent projects, ICU4C and ICU4J, led the team to realize that data management is the most critical aspect of deploying internationalization, and that it requires a high level of customization for the needs of the platform it is embedded in. As a result ICU4X comes with a selection of providers that should allow for ICU4X to naturally fit into different business and technological needs of customers.
icu_provider defines traits and structs for transmitting data through the ICU4X locale
data pipeline. The primary trait is
DataProvider. It is parameterized by a
KeyedDataMarker, which contains the data type and a
DataKey. It has one method,
DataProvider::load, which transforms a
DataKeyis a fixed identifier for the data type, such as
DataRequestcontains additional annotations to choose a specific variant of the key, such as a locale.
DataResponsecontains the data if the request was successful.
In addition, there are three other traits which are widely implemented:
AnyProviderreturns data as
dyn Anytrait objects.
BufferProviderreturns data as
DynamicDataProviderreturns structured data but is not specific to a key.
The most common types required for this crate are included via the prelude:
Types of Data Providers
All nontrivial data providers can fit into one of two classes.
AnyProvider: Those whose data originates as structured Rust objects
BufferProvider: Those whose data originates as unstructured
✨ Key Insight: A given data provider is generally either an
AnyProvider or a
BufferProvider. Which type depends on the data source, and it is not generally possible
to convert one to the other.
See also crate::constructors.
These providers are able to return structured data cast into
dyn Any trait objects. Users
as_downcasting() to get an object implementing
DataProvider by downcasting
the trait objects.
Examples of AnyProviders:
DatagenProviderreads structured data from CLDR source files and returns ICU4X data structs.
AnyPayloadProviderwraps a specific data struct and returns it.
BakedDataProviderwhich encodes structured data directly in Rust source
These providers are able to return unstructured data typically represented as
serde-serialized buffers. Users can call
as_deserializing() to get an object
DataProvider by invoking Serde Deserialize.
Examples of BufferProviders:
FsDataProviderreads individual buffers from the filesystem.
BlobDataProviderreads buffers from a large in-memory blob.
ICU4X offers several built-in modules to combine providers in interesting ways.
These can be found in the
This crate also contains a concrete provider for demonstration purposes:
HelloWorldProviderreturns “hello world” strings in several languages.
If you need a testing provider that contains the actual resource keys used by ICU4X features,
Types and Lifetimes
Types compatible with
Yokeable can be passed through the data provider, so long as they are
associated with a marker type implementing
Data structs should generally have one lifetime argument:
'data. This lifetime allows data
structs to borrow zero-copy data.
Data generation API
This functionality is enabled with the “datagen” Cargo feature
datagen module contains several APIs for data generation. See
icu_datagen for the reference
data generation implementation.
pub use crate::any::AnyMarker;
pub use crate::any::AnyPayload;
pub use crate::any::AnyProvider;
pub use crate::any::AnyResponse;
pub use crate::any::AsDowncastingAnyProvider;
pub use crate::any::AsDynamicDataProviderAnyMarkerWrap;
pub use crate::any::MaybeSendSync;
pub use crate::buf::BufferMarker;
pub use crate::buf::BufferProvider;
pub use crate::marker::DataMarker;
pub use crate::marker::KeyedDataMarker;
pub use crate::serde::AsDeserializingBufferProvider;
- Traits for data providers that produce
- Traits for data providers that produce opaque buffers.
- 📚 This module documents ICU4X constructor signatures.
- This module contains various utilities required to generate ICU4X data files, typically via the
icu_datagenreference crate. End users should not need to consume anything in this module as a library unless defining new types that integrate with
- Utilities for using trait objects with
- Data provider returning multilingual “Hello World” strings for testing.
- Marker types and traits for DataProvider.
- Core selection of APIs and structures for the ICU4X data provider.
- Provides the
DeserializingBufferProviderwrapper, which deserializes data using Serde.
UpcastDataPayloadfrom several data markers to a single data marker that all share the same
DynamicDataProviderfor a marker type
Son a type that already implements
DataProviderfor one or more
Mis a concrete type that is convertible to
- This macro can be used on a data provider to allow it to be used for data generation.
- The type of the “cart” that is used by
- The error type for ICU4X data provider operations.
- Used for loading data from an ICU4X data provider.
- A compact hash of a
DataKey. Useful for keys in maps.
- Metadata statically associated with a particular
- The string path of a data key. For example, “foo@1”
- The main locale type used by the ICU4X data provider.
- A container for data payloads returned from a data provider.
- The request type passed into all data provider implementations.
- Metadata for data requests. This is currently empty, but it may be extended with options for tuning locale fallback, buffer layout, and so forth.
- A response object containing an object as payload and metadata about it.
- A response object containing metadata about the returned data.
- A list specifying general categories of data provider error.
- Hint for what to prioritize during fallback when data is unavailable.
- What additional data to load when performing fallback.
- A data provider that loads data for a specific
- A data provider that loads data for a specific data type.
#[data_struct]attribute should be applied to all types intended for use in a