6 releases (breaking)

Uses new Rust 2021

0.6.0 May 10, 2022
0.5.0 Jan 31, 2022
0.4.0 Nov 2, 2021
0.3.0 Jul 29, 2021
0.1.0 Oct 15, 2020

#6 in Internationalization (i18n)

Download history 94/week @ 2022-01-30 14/week @ 2022-02-06 31/week @ 2022-02-13 17/week @ 2022-02-20 24/week @ 2022-02-27 32/week @ 2022-03-06 39/week @ 2022-03-13 51/week @ 2022-03-20 40/week @ 2022-03-27 63/week @ 2022-04-03 45/week @ 2022-04-10 52/week @ 2022-04-17 162/week @ 2022-04-24 194/week @ 2022-05-01 191/week @ 2022-05-08 867/week @ 2022-05-15

1,422 downloads per month
Used in 26 crates (21 directly)

Custom license

2MB
14K SLoC

icu_provider crates.io

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:

Special-Purpose Providers

This crate also contains some concrete implementations for testing purposes:

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.

More Information

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

Dependencies