vendor/icu_provider/src/buf.rs

   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
   7 use 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 pub struct BufferMarker;
  15
  16 impl DataMarker for BufferMarker {
  17     type Yokeable = &'static [u8];
  18 }
  19
  20 /// A data provider that returns opaque bytes.
  21 ///
  22 /// Generally, these bytes are expected to be deserializable with Serde. To get an object
  23 /// implementing [`DataProvider`] via Serde, use [`as_deserializing()`], which requires
  24 /// enabling at least one of the Serde features.
  25 ///
  26 /// Along with [`DataProvider`], this is one of the two foundational traits in this crate.
  27 ///
  28 /// [`BufferProvider`] can be made into a trait object. It is used over FFI.
  29 ///
  30 /// # Examples
  31 ///
  32 /// ```
  33 /// # #[cfg(feature = "deserialize_json")] {
  34 /// use icu_locid::locale;
  35 /// use icu_provider::hello_world::*;
  36 /// use icu_provider::prelude::*;
  37 ///
  38 /// let buffer_provider = HelloWorldProvider.into_json_provider();
  39 ///
  40 /// let data_provider = buffer_provider.as_deserializing();
  41 ///
  42 /// let german_hello_world: DataPayload<HelloWorldV1Marker> = data_provider
  43 ///     .load(DataRequest {
  44 ///         locale: &locale!("de").into(),
  45 ///         metadata: Default::default(),
  46 ///     })
  47 ///     .expect("Loading should succeed")
  48 ///     .take_payload()
  49 ///     .expect("Data should be present");
  50 ///
  51 /// assert_eq!("Hallo Welt", german_hello_world.get().message);
  52 /// # }
  53 /// ```
  54 ///
  55 /// [`as_deserializing()`]: AsDeserializingBufferProvider::as_deserializing
  56 pub trait BufferProvider {
  57     /// Loads a [`DataPayload`]`<`[`BufferMarker`]`>` according to the key and request.
  58     fn load_buffer(
  59         &self,
  60         key: DataKey,
  61         req: DataRequest,
  62     ) -> Result<DataResponse<BufferMarker>, DataError>;
  63 }
  64
  65 impl<T: BufferProvider + ?Sized> BufferProvider for alloc::boxed::Box<T> {
  66     fn load_buffer(
  67         &self,
  68         key: DataKey,
  69         req: DataRequest,
  70     ) -> Result<DataResponse<BufferMarker>, DataError> {
  71         (**self).load_buffer(key, req)
  72     }
  73 }
  74
  75 /// An enum expressing all Serde formats known to ICU4X.
  76 #[derive(Debug, PartialEq, Eq, Hash, Copy, Clone)]
  77 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
  78 #[non_exhaustive]
  79 pub enum BufferFormat {
  80     /// Serialize using JavaScript Object Notation (JSON).
  81     Json,
  82     /// Serialize using Bincode version 1.
  83     Bincode1,
  84     /// Serialize using Postcard version 0.7.
  85     Postcard1,
  86 }
  87
  88 impl BufferFormat {
  89     /// Returns an error if the buffer format is not enabled.
  90     pub fn check_available(&self) -> Result<(), DataError> {
  91         match self {
  92             #[cfg(feature = "deserialize_json")]
  93             BufferFormat::Json => Ok(()),
  94
  95             #[cfg(feature = "deserialize_bincode_1")]
  96             BufferFormat::Bincode1 => Ok(()),
  97
  98             #[cfg(feature = "deserialize_postcard_1")]
  99             BufferFormat::Postcard1 => Ok(()),
 100
 101             // Allowed for cases in which all features are enabled
 102             #[allow(unreachable_patterns)]
 103             _ => Err(DataErrorKind::UnavailableBufferFormat(*self).into_error()),
 104         }
 105     }
 106 }