serde-human-bytes 0.1.3

//! Wrapper types to enable optimized handling of `&[u8]` and `Vec<u8>`.
//!
//! Without specialization, Rust forces Serde to treat `&[u8]` just like any
//! other slice and `Vec<u8>` just like any other vector. In reality this
//! particular slice and vector can often be serialized and deserialized in a
//! more efficient, compact representation in many formats.
//!
//! When working with such a format, you can opt into specialized handling of
//! `&[u8]` by wrapping it in `serde_human_bytes::Bytes` and `Vec<u8>` by wrapping it
//! in `serde_human_bytes::ByteBuf`.
//!
//! Additionally this crate supports the Serde `with` attribute to enable
//! efficient handling of `&[u8]` and `Vec<u8>` in structs without needing a
//! wrapper type.
//!
//! ```
//! # use serde_derive::{Deserialize, Serialize};
//! use serde::{Deserialize, Serialize};
//!
//! #[derive(Deserialize, Serialize)]
//! struct Efficient<'a> {
//!     #[serde(with = "serde_human_bytes")]
//!     bytes: &'a [u8],
//!
//!     #[serde(with = "serde_human_bytes")]
//!     byte_buf: Vec<u8>,
//!
//!     #[serde(with = "serde_human_bytes")]
//!     byte_array: [u8; 314],
//! }
//! ```

#![doc(html_root_url = "https://docs.rs/serde_human_bytes/0.11.15")]
#![cfg_attr(not(feature = "std"), no_std)]
#![deny(missing_docs)]
#![allow(
    clippy::into_iter_without_iter,
    clippy::missing_errors_doc,
    clippy::must_use_candidate,
    clippy::needless_doctest_main,
    clippy::needless_lifetimes,
    clippy::ptr_as_ptr
)]

pub mod base64;
mod bytearray;
mod bytes;
mod codec;
mod de;
mod ser;

mod bytebuf;

extern crate alloc;

use serde::{Deserializer, Serializer};

pub use crate::bytearray::ByteArray;
pub use crate::bytes::Bytes;
pub use crate::codec::{Base64, Codec, LowerHex, UpperHex};
pub use crate::de::Deserialize;
pub use crate::ser::Serialize;

pub use crate::bytebuf::ByteBuf;

/// Serde `serialize_with` function to serialize bytes efficiently.
///
/// This function can be used with either of the following Serde attributes:
///
/// - `#[serde(with = "serde_human_bytes")]`
/// - `#[serde(serialize_with = "serde_human_bytes::serialize")]`
///
/// ```
/// # use serde_derive::Serialize;
/// use serde::Serialize;
///
/// #[derive(Serialize)]
/// struct Efficient<'a> {
///     #[serde(with = "serde_human_bytes")]
///     bytes: &'a [u8],
///
///     #[serde(with = "serde_human_bytes")]
///     byte_buf: Vec<u8>,
///
///     #[serde(with = "serde_human_bytes")]
///     byte_array: [u8; 314],
/// }
/// ```
pub fn serialize<T, S>(bytes: &T, serializer: S) -> Result<S::Ok, S::Error>
where
    T: ?Sized + Serialize,
    S: Serializer,
{
    Serialize::serialize(bytes, serializer)
}

/// Serde `deserialize_with` function to deserialize bytes efficiently.
///
/// This function can be used with either of the following Serde attributes:
///
/// - `#[serde(with = "serde_human_bytes")]`
/// - `#[serde(deserialize_with = "serde_human_bytes::deserialize")]`
///
/// ```
/// # use serde_derive::Deserialize;
/// use serde::Deserialize;
///
/// #[derive(Deserialize)]
/// struct Packet {
///     #[serde(with = "serde_human_bytes")]
///     payload: Vec<u8>,
///
///     #[serde(with = "serde_human_bytes")]
///     byte_array: [u8; 314],
/// }
/// ```
pub fn deserialize<'de, T, D>(deserializer: D) -> Result<T, D::Error>
where
    T: Deserialize<'de>,
    D: Deserializer<'de>,
{
    Deserialize::deserialize(deserializer)
}

/// UPPERCASE hex variant of the parent module.
///
/// Use as `#[serde(with = "serde_human_bytes::upper")]` when the wire format
/// requires uppercase hex (e.g. Intel SGX/TDX PCCS payloads). Identical to
/// the parent module for non-human-readable formats (still emits a compact
/// byte sequence) and for deserialization (still case-insensitive).
///
/// ```
/// # use serde_derive::{Deserialize, Serialize};
/// use serde::{Deserialize, Serialize};
///
/// #[derive(Deserialize, Serialize)]
/// struct Identity {
///     #[serde(with = "serde_human_bytes::upper")]
///     mrsigner: [u8; 32],
/// }
/// ```
pub mod upper {
    use serde::{Deserializer, Serializer};

    /// Serde `serialize_with` function emitting UPPERCASE hex.
    pub fn serialize<T, S>(value: &T, serializer: S) -> Result<S::Ok, S::Error>
    where
        T: ?Sized + crate::Serialize<crate::UpperHex>,
        S: Serializer,
    {
        crate::Serialize::<crate::UpperHex>::serialize(value, serializer)
    }

    /// Serde `deserialize_with` function — case-insensitive hex.
    pub fn deserialize<'de, T, D>(deserializer: D) -> Result<T, D::Error>
    where
        T: crate::Deserialize<'de, crate::UpperHex>,
        D: Deserializer<'de>,
    {
        crate::Deserialize::<'de, crate::UpperHex>::deserialize(deserializer)
    }
}