Crate icu_provider
source · [−]Expand description
icu_provider
is one of the ICU4X
components.
icu_provider
defines traits and structs for transmitting data through the ICU4X locale
data pipeline. The primary trait is ResourceProvider
. It is parameterized by a
ResourceMarker
, which contains the data type and a ResourceKey
. It has one method,
ResourceProvider::load_resource
, which transforms a DataRequest
into a DataResponse
.
ResourceKey
is a fixed identifier for the data type, such as"plurals/cardinal@1"
.DataRequest
contains additional annotations to choose a specific variant of the key, such as a locale.DataResponse
contains the data if the request was successful.
In addition, there are three other traits which are widely implemented:
AnyProvider
returns data asdyn Any
trait objects.BufferProvider
returns data as[u8]
buffers.DynProvider
returns structured data but is not specific to a key.
The most common types required for this crate are included via the prelude:
use icu_provider::prelude::*;
Types of Data Providers
All nontrivial data providers can fit into one of two classes.
- Type 1: Those whose data originates as structured Rust objects
- Type 2: Those whose data originates as unstructured
[u8]
buffers
Type 1 Providers
Type 1 providers generally implement AnyProvider
, which returns structured data cast into
dyn Any
trait objects. Users can call as_downcasting()
to get an object implementing
ResourceProvider
by downcasting the trait objects.
Examples of Type 1 providers:
CldrJsonDataProvider
reads structured data from CLDR JSON source files and returns structured Rust objects.AnyPayloadProvider
wraps a specific data struct and returns it.- The upcoming
crabbake
provider which reads structured data from Rust source files
Type 2 Providers
Type 2 providers generally implement BufferProvider
, which returns unstructured data
typically represented as serde
-serialized buffers. Users can call as_deserializing()
to get an object implementing ResourceProvider
by invoking Serde Deserialize.
Examples of Type 2 providers:
FsDataProvider
reads individual buffers from the filesystem.BlobDataProvider
reads buffers from a large in-memory blob.
Special-Purpose Providers
This crate also contains some concrete implementations for testing purposes:
InvariantDataProvider
returns fixed data that does not vary by locale.HelloWorldProvider
returns “hello world” strings in several languages.
Provider Adapters
ICU4X offers several built-in modules to combine providers in interesting ways.
These can be found in the icu_provider_adapters
crate.
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 DataMarker
.
Data structs should generally have one lifetime argument: 'data
. This lifetime allows data
structs to borrow zero-copy data.
Additional Traits
DataProvider<SerializeMarker>
Enabled with the “datagen” feature
Data providers capable of returning opaque erased_serde::Serialize
trait objects can be use
as input to a data exporter, such as when writing data to the filesystem.
This trait is normally implemented using the impl_dyn_provider!
macro.
IterableDataProvider
Enabled with the “datagen” feature
Data providers can implement IterableDynProvider
/IterableResourceProvider
, allowing
iteration over all ResourceOptions
instances supported for a certain key in the data provider.
This trait is normally implemented using the impl_dyn_provider!
macro using the ITERABLE_SERDE_SE
option.
Re-exports
Modules
Traits for data providers that produce Any
objects.
Traits for data providers that produce opaque buffers.
This module contains various utilities required to generate ICU4X data files, typically
via the icu4x-datagen
tool. End users should not need to consume anything in this module
as a library unless defining new types that integrate with icu4x-datagen
.
Utilities for using trait objects with DataPayload
.
Types having to do with the exporting of data.
Data provider returning multilingual “Hello World” strings for testing.
Locale-invariant data provider that requires no I/O.
Marker types and traits for DataProvider.
Core selection of APIs and structures for the ICU4X data provider.
Collection of traits for providers that support serializing or deserializing data.
Macros
Implements ResourceProvider and DynProvider if BufferProvider is implemented.
This allows dropping the call to .as_deserializing()
.
Implements DynProvider
for a marker type S
on a type that already implements
DynProvider
or ResourceProvider
for one or more M
, where M
is a concrete type
that is convertible to S
via UpcastDataPayload
.
Attribute Macros
The #[data_struct]
attribute should be applied to all types intended
for use in a DataStruct
. It does the following things: