1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
|
# icu_provider [](https://crates.io/crates/icu_provider)
<!-- cargo-rdme start -->
`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:
```rust
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<BufferMarker>`], a.k.a. [`BufferProvider`](buf::BufferProvider) returns data as `[u8]` buffers.
#### 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.
[`FixedProvider`]: https://docs.rs/icu_provider_adapters/latest/fixed/any_payload/struct.FixedProvider.html
[`HelloWorldProvider`]: hello_world::HelloWorldProvider
[`Yokeable`]: yoke::Yokeable
[`impl_dynamic_data_provider!`]: dynutil::impl_dynamic_data_provider
[`icu_provider_adapters`]: https://docs.rs/icu_provider_adapters/latest/icu_provider_adapters/index.html
[`SourceDataProvider`]: https://docs.rs/icu_provider_source/latest/icu_provider_source/struct.SourceDataProvider.html
[`as_deserializing()`]: buf::AsDeserializingBufferProvider::as_deserializing
[`FsDataProvider`]: https://docs.rs/icu_provider_fs/latest/icu_provider_fs/struct.FsDataProvider.html
[`BlobDataProvider`]: https://docs.rs/icu_provider_blob/latest/icu_provider_blob/struct.BlobDataProvider.html
<!-- cargo-rdme end -->
## More Information
For more information on development, authorship, contributing etc. please visit [`ICU4X home page`](https://github.com/unicode-org/icu4x).
|
