Crate icu_provider

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 as dyn 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.

1. Type 1: Those whose data originates as structured Rust objects
2. 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

pub use yoke;

pub use zerofrom;

pub use prelude::*;

Modules

any

Traits for data providers that produce Any objects.

buf

Traits for data providers that produce opaque buffers.

datagen

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.

dynutil

Utilities for using trait objects with DataPayload.

export

Types having to do with the exporting of data.

hello_world

Data provider returning multilingual “Hello World” strings for testing.

inv

Locale-invariant data provider that requires no I/O.

marker

Marker types and traits for DataProvider.

prelude

Core selection of APIs and structures for the ICU4X data provider.

serde

Collection of traits for providers that support serializing or deserializing data.

Macros

impl_auto_deserializing

Implements ResourceProvider and DynProvider if BufferProvider is implemented. This allows dropping the call to .as_deserializing().

impl_dyn_provider

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.

resource_key

See ResourceKey.

Attribute Macros

data_struct

The #[data_struct] attribute should be applied to all types intended for use in a DataStruct. It does the following things: