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 [DataProvider]. It is parameterized by a [KeyedDataMarker], which contains the data type and a [DataKey]. It has one method, [DataProvider::load], which transforms a [DataRequest] into a [DataResponse].

• [DataKey] 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.
• [DynamicDataProvider] returns structured data but is not specific to a key.

The most common types required for this crate are included via the prelude:

rust use icu_provider::prelude::*;

Types of Data Providers

All nontrivial data providers can fit into one of two classes.

1. [AnyProvider]: Those whose data originates as structured Rust objects
2. [BufferProvider]: Those whose data originates as unstructured [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:

• [CldrJsonDataProvider] reads structured data from CLDR JSON source files and returns structured Rust objects.
• [AnyPayloadProvider] wraps a specific data struct and returns it.
• The BakedDataProvider which encodes structured data directly in Rust source

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.

ICU4X Constructors and Data Versioning Policy

A design goal of ICU4X is to enable data sharing across ICU4X library versions. In order to achieve this stability and still allow data structs to evolve, there are 3 versions of all ICU4X functions that take a data provider:

1. *_unstable
2. *_with_any_provider
3. *_with_buffer_provider

The *_with_any_provider and *_with_buffer_provider functions will succeed if given a data provider supporting all of the keys required for the object being constructed, either the current or any previous version within the same SemVer major release. For example, if a data file is built to support FooFormatter version 1.1, then FooFormatter version 1.2 will be able to read the same data file. Likewise, backwards-compatible keys can always be included by [icu_datagen] to support older library versions.

The *_unstable functions are only guaranteed to work on data built for the exact same version of ICU4X. The advantage of the *_unstable functions is that they result in the smallest code size and allow for automatic data slicing when BakedDataProvider is used. However, the type bounds of this function may change over time, breaking SemVer guarantees. These functions should therefore only be used when you have full control over your data lifecycle.

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 testing purposes:

• [HelloWorldProvider] returns "hello world" strings in several languages.

If you need a testing provider that contains the actual resource keys used by ICU4X features, see the [icu_testdata] 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.

Data generation API

This functionality is enabled with the "datagen" feature

The [datagen] module contains several APIs for data generation. See [icu_datagen] for the reference data generation implementation.

More Information

For more information on development, authorship, contributing etc. please visit ICU4X home page.