Crate icu_provider
source ·Expand description
icu_provider
is one of the ICU4X
components.
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
DataMarker
, which is the type-system-level data identifier. DataProvider
has a single method,
DataProvider::load
, which transforms a DataRequest
into a DataResponse
.
DataRequest
contains selectors to choose a specific variant of the marker, such as a locale.DataResponse
contains the data if the request was successful.
The most common types required for this crate are included via the prelude:
use icu_provider::prelude::*;
§Dynamic Data Providers
If the type system cannot be leveraged to load data (such as when dynamically loading from I/O),
there’s another form of the DataProvider
: DynamicDataProvider
. While DataProvider
is parametrized
on the type-system level by a DataMarker
(which are distinct types implementing this trait),
DynamicDataProvider
s are parametrized at runtime by a DataMarkerInfo
struct, which essentially is the runtime
representation of the DataMarker
type.
The DynamicDataProvider
is still type-level parametrized by the type that it loads, and there are two
implementations that should be called out
DynamicDataProvider<AnyMarker>
, andAnyProvider
(a slightly optimized alternative) return data asdyn Any
trait objects.DynamicDataProvider<BufferMarker>
, a.k.a.BufferProvider
returns data as[u8]
buffers.
§AnyProvider
These providers are able to return structured data cast into dyn Any
trait objects. Users
can call as_downcasting()
to get an object implementing DataProvider
by downcasting
the trait objects.
Examples of AnyProviders:
FixedProvider
wraps a specific data struct and returns it.
§BufferProvider
These providers are able to return unstructured data typically represented as
serde
-serialized buffers. Users can call as_deserializing()
to get an object
implementing DataProvider
by invoking Serde Deserialize.
Examples of BufferProviders:
FsDataProvider
reads individual buffers from the filesystem.BlobDataProvider
reads buffers from a large in-memory blob.
§Provider Adapters
ICU4X offers several built-in modules to combine providers in interesting ways.
These can be found in the icu_provider_adapters
crate.
§Testing Provider
This crate also contains a concrete provider for demonstration purposes:
HelloWorldProvider
returns “hello world” strings in several languages.
§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 DynamicDataMarker
.
Data structs should generally have one lifetime argument: 'data
. This lifetime allows data
structs to borrow zero-copy data.
Modules§
- Traits for data providers that produce
Any
objects. - Traits for data providers that produce opaque buffers.
- 📚 This module documents ICU4X constructor signatures.
- Utilities for using trait objects with
DataPayload
. - This module contains types required to export ICU4X data via the
icu_provider_export
crate. End users should not need to consume anything in this module. - Data provider returning multilingual “Hello World” strings for testing.
- Additional
DataMarker
helpers. - Core selection of APIs and structures for the ICU4X data provider.
Structs§
- Invalid character
- The type of the “cart” that is used by
DataPayload
. - The error type for ICU4X data provider operations.
- The borrowed version of a
DataIdentifierCow
. - A data identifier identifies a particular version of data, such as “English”.
- A locale type optimized for use in fallbacking and the ICU4X data pipeline.
- An additional key to identify data beyond a
DataLocale
. - Used for loading data from a dynamic ICU4X data provider.
- A container for data payloads returned from a data provider.
- A
DataProvider
associated with a specific marker. - 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.
Enums§
- A list specifying general categories of data provider error.
Traits§
- A data provider that loads data for a specific data type.
- A
DynamicDataMarker
with aDataMarkerInfo
attached. - A data provider that loads data for a specific
DataMarkerInfo
. - A data provider that can determine whether it can load a particular data identifier, potentially cheaper than actually performing the load.
- Trait marker for data structs. All types delivered by the data provider must be associated with something implementing this trait.
- A data provider that loads data for a specific data type.
- A dynanmic data provider that can determine whether it can load a particular data identifier, potentially cheaper than actually performing the load.
- A
DataProvider
that can iterate over all supportedDataIdentifierCow
s. - A
DynamicDataProvider
that can iterate over all supportedDataIdentifierCow
s for a certain marker. - Extension trait for
Result<T, DataError>
.
Attribute Macros§
- The
#[data_struct]
attribute should be applied to all types intended for use in aDataStruct
.