serde_bytes/
lib.rs

1//! Wrapper types to enable optimized handling of `&[u8]` and `Vec<u8>`.
2//!
3//! Without specialization, Rust forces Serde to treat `&[u8]` just like any
4//! other slice and `Vec<u8>` just like any other vector. In reality this
5//! particular slice and vector can often be serialized and deserialized in a
6//! more efficient, compact representation in many formats.
7//!
8//! When working with such a format, you can opt into specialized handling of
9//! `&[u8]` by wrapping it in `serde_bytes::Bytes` and `Vec<u8>` by wrapping it
10//! in `serde_bytes::ByteBuf`.
11//!
12//! Additionally this crate supports the Serde `with` attribute to enable
13//! efficient handling of `&[u8]` and `Vec<u8>` in structs without needing a
14//! wrapper type.
15//!
16//! ```
17//! # use serde_derive::{Deserialize, Serialize};
18//! use serde::{Deserialize, Serialize};
19//!
20//! #[derive(Deserialize, Serialize)]
21//! struct Efficient<'a> {
22//!     #[serde(with = "serde_bytes")]
23//!     bytes: &'a [u8],
24//!
25//!     #[serde(with = "serde_bytes")]
26//!     byte_buf: Vec<u8>,
27//!
28//!     #[serde(with = "serde_bytes")]
29//!     byte_array: [u8; 314],
30//! }
31//! ```
32
33#![doc(html_root_url = "https://docs.rs/serde_bytes/0.11.19")]
34#![cfg_attr(not(feature = "std"), no_std)]
35#![deny(missing_docs)]
36#![allow(
37    clippy::elidable_lifetime_names,
38    clippy::into_iter_without_iter,
39    clippy::missing_errors_doc,
40    clippy::must_use_candidate,
41    clippy::needless_doctest_main,
42    clippy::needless_lifetimes,
43    clippy::ptr_as_ptr
44)]
45
46extern crate serde_core as serde;
47
48mod bytearray;
49mod bytes;
50mod de;
51mod ser;
52
53#[cfg(any(feature = "std", feature = "alloc"))]
54mod bytebuf;
55
56#[cfg(feature = "alloc")]
57extern crate alloc;
58
59use serde::{Deserializer, Serializer};
60
61pub use crate::bytearray::ByteArray;
62pub use crate::bytes::Bytes;
63pub use crate::de::Deserialize;
64pub use crate::ser::Serialize;
65
66#[cfg(any(feature = "std", feature = "alloc"))]
67pub use crate::bytebuf::ByteBuf;
68
69/// Serde `serialize_with` function to serialize bytes efficiently.
70///
71/// This function can be used with either of the following Serde attributes:
72///
73/// - `#[serde(with = "serde_bytes")]`
74/// - `#[serde(serialize_with = "serde_bytes::serialize")]`
75///
76/// ```
77/// # use serde_derive::Serialize;
78/// use serde::Serialize;
79///
80/// #[derive(Serialize)]
81/// struct Efficient<'a> {
82///     #[serde(with = "serde_bytes")]
83///     bytes: &'a [u8],
84///
85///     #[serde(with = "serde_bytes")]
86///     byte_buf: Vec<u8>,
87///
88///     #[serde(with = "serde_bytes")]
89///     byte_array: [u8; 314],
90/// }
91/// ```
92pub fn serialize<T, S>(bytes: &T, serializer: S) -> Result<S::Ok, S::Error>
93where
94    T: ?Sized + Serialize,
95    S: Serializer,
96{
97    Serialize::serialize(bytes, serializer)
98}
99
100/// Serde `deserialize_with` function to deserialize bytes efficiently.
101///
102/// This function can be used with either of the following Serde attributes:
103///
104/// - `#[serde(with = "serde_bytes")]`
105/// - `#[serde(deserialize_with = "serde_bytes::deserialize")]`
106///
107/// ```
108/// # use serde_derive::Deserialize;
109/// use serde::Deserialize;
110///
111/// #[derive(Deserialize)]
112/// struct Packet {
113///     #[serde(with = "serde_bytes")]
114///     payload: Vec<u8>,
115///
116///     #[serde(with = "serde_bytes")]
117///     byte_array: [u8; 314],
118/// }
119/// ```
120pub fn deserialize<'de, T, D>(deserializer: D) -> Result<T, D::Error>
121where
122    T: Deserialize<'de>,
123    D: Deserializer<'de>,
124{
125    Deserialize::deserialize(deserializer)
126}
serde_bytes/lib.rs

serde_bytes/
lib.rs
