sparse_hash_map/
serialize.rs

1//! Serialization protocol for maps and sets.
2//!
3//! The container writes a fixed sequence of fields through a [`Serializer`] and
4//! reads them back through a [`Deserializer`]. The protocol defines the order
5//! and logical type of each field. Binary layout, endianness, and float
6//! representation are the caller's responsibility, chosen by the serializer and
7//! deserializer they supply.
8//!
9//! Integer header fields are always [`u64`] so a file written on one platform
10//! can be read on another. The value type is serialized through
11//! [`Serialize`]/[`Deserialize`] implementations.
12
13/// The serialization protocol version. Bumped on any wire-format change.
14pub const SERIALIZATION_PROTOCOL_VERSION: u64 = 1;
15
16/// A sink for the primitive field types the container emits.
17///
18/// Implement this to control the binary layout. The container calls these in a
19/// fixed order.
20pub trait Serializer {
21    /// Write a 64-bit integer field.
22    fn write_u64(&mut self, value: u64);
23    /// Write a 32-bit float field.
24    fn write_f32(&mut self, value: f32);
25    /// Write raw bytes, such as string contents.
26    fn write_bytes(&mut self, bytes: &[u8]);
27}
28
29/// A source for the primitive field types the container reads back.
30///
31/// The order of reads matches the order of writes in [`Serializer`].
32pub trait Deserializer {
33    /// Read a 64-bit integer field.
34    fn read_u64(&mut self) -> u64;
35    /// Read a 32-bit float field.
36    fn read_f32(&mut self) -> f32;
37    /// Read `len` raw bytes.
38    fn read_bytes(&mut self, len: usize) -> Vec<u8>;
39
40    /// Bytes still available to read, when the source knows its length.
41    ///
42    /// A variable-length [`Deserialize`] impl checks this before allocating a
43    /// buffer sized by a length read from the input. A source that cannot report
44    /// its length returns `None`, and the impl allocates as before. The default
45    /// returns `None`.
46    fn remaining(&self) -> Option<usize> {
47        None
48    }
49}
50
51/// A value type that can be written to a [`Serializer`].
52pub trait Serialize {
53    /// Emit this value's fields.
54    fn serialize<S: Serializer>(&self, serializer: &mut S);
55}
56
57/// A value type that can be read from a [`Deserializer`].
58pub trait Deserialize: Sized {
59    /// Read one value.
60    ///
61    /// This returns `Self`, not a `Result`, so an impl signals a malformed value
62    /// by panicking. The `String` impl panics on a length that overruns the
63    /// input or on invalid UTF-8. A caller reading untrusted bytes should guard
64    /// against a panic here.
65    fn deserialize<D: Deserializer>(deserializer: &mut D) -> Self;
66}
67
68macro_rules! impl_int_serialize {
69    ($($t:ty),*) => {$(
70        impl Serialize for $t {
71            fn serialize<S: Serializer>(&self, serializer: &mut S) {
72                serializer.write_u64(*self as u64);
73            }
74        }
75        impl Deserialize for $t {
76            fn deserialize<D: Deserializer>(deserializer: &mut D) -> Self {
77                deserializer.read_u64() as $t
78            }
79        }
80    )*};
81}
82
83impl_int_serialize!(u8, u16, u32, u64, usize, i8, i16, i32, i64, isize);
84
85impl Serialize for String {
86    fn serialize<S: Serializer>(&self, serializer: &mut S) {
87        serializer.write_u64(self.len() as u64);
88        serializer.write_bytes(self.as_bytes());
89    }
90}
91
92impl Deserialize for String {
93    fn deserialize<D: Deserializer>(deserializer: &mut D) -> Self {
94        let len = deserializer.read_u64() as usize;
95        if let Some(remaining) = deserializer.remaining() {
96            assert!(
97                len <= remaining,
98                "deserialized string length {len} exceeds the {remaining} bytes left in the input"
99            );
100        }
101        let bytes = deserializer.read_bytes(len);
102        String::from_utf8(bytes).expect("deserialized string is not valid utf-8")
103    }
104}
105
106impl<A: Serialize, B: Serialize> Serialize for (A, B) {
107    fn serialize<S: Serializer>(&self, serializer: &mut S) {
108        self.0.serialize(serializer);
109        self.1.serialize(serializer);
110    }
111}
112
113impl<A: Deserialize, B: Deserialize> Deserialize for (A, B) {
114    fn deserialize<D: Deserializer>(deserializer: &mut D) -> Self {
115        let a = A::deserialize(deserializer);
116        let b = B::deserialize(deserializer);
117        (a, b)
118    }
119}
120
121/// A deserialize failure. Carries a static reason.
122#[derive(Debug, Clone, Copy, PartialEq, Eq)]
123pub struct DeserializeError(pub &'static str);
124
125impl core::fmt::Display for DeserializeError {
126    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
127        f.write_str(self.0)
128    }
129}
130
131impl std::error::Error for DeserializeError {}
sparse_hash_map/serialize.rs

sparse_hash_map/
serialize.rs
