icu_provider/
buf.rs

Help
1// This file is part of ICU4X. For terms of use, please see the file
2// called LICENSE at the top level of the ICU4X source tree
3// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ).
4
5//! Traits for data providers that produce opaque buffers.
6
7use crate::prelude::*;
8
9/// [`DataMarker`] for raw buffers. Returned by [`BufferProvider`].
10///
11/// The data is expected to be deserialized before it can be used; see
12/// [`DataPayload::into_deserialized`].
13#[allow(clippy::exhaustive_structs)] // marker type
14#[derive(Debug)]
15pub struct BufferMarker;
16
17impl DataMarker for BufferMarker {
18    type Yokeable = &'static [u8];
19}
20
21/// A data provider that returns opaque bytes.
22///
23/// Generally, these bytes are expected to be deserializable with Serde. To get an object
24/// implementing [`DataProvider`] via Serde, use [`as_deserializing()`].
25///
26/// Passing a  `BufferProvider` to a `*_with_buffer_provider` constructor requires enabling
27/// the deserialization Cargo feature for the expected format(s):
28/// - `deserialize_json`
29/// - `deserialize_postcard_1`
30/// - `deserialize_bincode_1`
31///
32/// Along with [`DataProvider`], this is one of the two foundational traits in this crate.
33///
34/// [`BufferProvider`] can be made into a trait object. It is used over FFI.
35///
36/// # Examples
37///
38/// ```
39/// # #[cfg(feature = "deserialize_json")] {
40/// use icu_locid::langid;
41/// use icu_provider::hello_world::*;
42/// use icu_provider::prelude::*;
43/// use std::borrow::Cow;
44///
45/// let buffer_provider = HelloWorldProvider.into_json_provider();
46///
47/// let req = DataRequest {
48///     locale: &langid!("de").into(),
49///     metadata: Default::default(),
50/// };
51///
52/// // Deserializing manually
53/// assert_eq!(
54///     serde_json::from_slice::<HelloWorldV1>(
55///         buffer_provider
56///             .load_buffer(HelloWorldV1Marker::KEY, req)
57///             .expect("load should succeed")
58///             .take_payload()
59///             .unwrap()
60///             .get()
61///     )
62///     .expect("should deserialize"),
63///     HelloWorldV1 {
64///         message: Cow::Borrowed("Hallo Welt"),
65///     },
66/// );
67///
68/// // Deserialize automatically
69/// let deserializing_provider: &dyn DataProvider<HelloWorldV1Marker> =
70///     &buffer_provider.as_deserializing();
71///
72/// assert_eq!(
73///     deserializing_provider
74///         .load(req)
75///         .expect("load should succeed")
76///         .take_payload()
77///         .unwrap()
78///         .get(),
79///     &HelloWorldV1 {
80///         message: Cow::Borrowed("Hallo Welt"),
81///     },
82/// );
83/// # }
84/// ```
85///
86/// [`as_deserializing()`]: AsDeserializingBufferProvider::as_deserializing
87pub trait BufferProvider {
88    /// Loads a [`DataPayload`]`<`[`BufferMarker`]`>` according to the key and request.
89    fn load_buffer(
90        &self,
91        key: DataKey,
92        req: DataRequest,
93    ) -> Result<DataResponse<BufferMarker>, DataError>;
94}
95
96impl<'a, T: BufferProvider + ?Sized> BufferProvider for &'a T {
97    #[inline]
98    fn load_buffer(
99        &self,
100        key: DataKey,
101        req: DataRequest,
102    ) -> Result<DataResponse<BufferMarker>, DataError> {
103        (**self).load_buffer(key, req)
104    }
105}
106
107impl<T: BufferProvider + ?Sized> BufferProvider for alloc::boxed::Box<T> {
108    #[inline]
109    fn load_buffer(
110        &self,
111        key: DataKey,
112        req: DataRequest,
113    ) -> Result<DataResponse<BufferMarker>, DataError> {
114        (**self).load_buffer(key, req)
115    }
116}
117
118impl<T: BufferProvider + ?Sized> BufferProvider for alloc::rc::Rc<T> {
119    #[inline]
120    fn load_buffer(
121        &self,
122        key: DataKey,
123        req: DataRequest,
124    ) -> Result<DataResponse<BufferMarker>, DataError> {
125        (**self).load_buffer(key, req)
126    }
127}
128
129#[cfg(target_has_atomic = "ptr")]
130impl<T: BufferProvider + ?Sized> BufferProvider for alloc::sync::Arc<T> {
131    #[inline]
132    fn load_buffer(
133        &self,
134        key: DataKey,
135        req: DataRequest,
136    ) -> Result<DataResponse<BufferMarker>, DataError> {
137        (**self).load_buffer(key, req)
138    }
139}
140
141/// An enum expressing all Serde formats known to ICU4X.
142#[derive(Debug, PartialEq, Eq, Hash, Copy, Clone)]
143#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
144#[non_exhaustive]
145pub enum BufferFormat {
146    /// Serialize using JavaScript Object Notation (JSON).
147    Json,
148    /// Serialize using Bincode version 1.
149    Bincode1,
150    /// Serialize using Postcard version 1.
151    Postcard1,
152}
153
154impl BufferFormat {
155    /// Returns an error if the buffer format is not enabled.
156    pub fn check_available(&self) -> Result<(), DataError> {
157        match self {
158            #[cfg(feature = "deserialize_json")]
159            BufferFormat::Json => Ok(()),
160
161            #[cfg(feature = "deserialize_bincode_1")]
162            BufferFormat::Bincode1 => Ok(()),
163
164            #[cfg(feature = "deserialize_postcard_1")]
165            BufferFormat::Postcard1 => Ok(()),
166
167            // Allowed for cases in which all features are enabled
168            #[allow(unreachable_patterns)]
169            _ => Err(DataErrorKind::UnavailableBufferFormat(*self).into_error()),
170        }
171    }
172}
icu_provider/buf.rs

icu_provider/
buf.rs
