serde_binary/
lib.rs

1//! Serializer and deserializer for binary data.
2//!
3//! Sequences and maps that encode a length prefix use a `u32` for
4//! portability across platforms which limits the number of
5//! items in sequences and maps to 2^32.
6//!
7mod deserializer;
8mod error;
9mod serializer;
10
11use serde::{de::Deserialize, de::DeserializeOwned, Serialize};
12
13use binary_stream::{BinaryReader, BinaryWriter, Endian, MemoryStream, SliceStream};
14
15pub use binary_stream;
16pub use {deserializer::Deserializer, error::Error, serializer::Serializer};
17
18/// Result type for serialization and deserialization.
19pub type Result<T> = std::result::Result<T, Error>;
20
21/// Serialize to an owned buffer.
22pub fn to_vec<T>(value: &T, endian: Endian) -> Result<Vec<u8>>
23where
24    T: ?Sized + Serialize,
25{
26    let mut stream = MemoryStream::new();
27    let writer = BinaryWriter::new(&mut stream, endian);
28    let mut serializer = Serializer { writer };
29    value.serialize(&mut serializer)?;
30    Ok(stream.into())
31}
32
33/// Deserialize from an owned buffer.
34pub fn from_vec<T>(value: Vec<u8>, endian: Endian) -> Result<T>
35where
36    T: DeserializeOwned,
37{
38    from_slice(&value, endian)
39}
40
41/// Deserialize from a slice of bytes.
42pub fn from_slice<T>(value: &[u8], endian: Endian) -> Result<T>
43where
44    T: DeserializeOwned,
45{
46    let mut stream = SliceStream::new(value);
47    let reader = BinaryReader::new(&mut stream, endian);
48    let mut deserializer = Deserializer { reader };
49    let value: T = Deserialize::deserialize(&mut deserializer)?;
50    Ok(value)
51}
52
53/// Serialize an `Encode` implementation into binary data.
54pub fn encode(encodable: &impl Encode, endian: Endian) -> Result<Vec<u8>> {
55    let mut stream = MemoryStream::new();
56    let writer = BinaryWriter::new(&mut stream, endian);
57    let mut serializer = Serializer { writer };
58    encodable.encode(&mut serializer)?;
59    Ok(stream.into())
60}
61
62/// Deserialize a `Decode` implementation from binary data.
63///
64/// The type must also implement the `Default` trait.
65pub fn decode<T: Decode + Default>(buffer: &[u8], endian: Endian) -> Result<T> {
66    let mut stream = SliceStream::new(buffer);
67    let reader = BinaryReader::new(&mut stream, endian);
68    let mut deserializer = Deserializer { reader };
69    let mut decoded: T = T::default();
70    decoded.decode(&mut deserializer)?;
71    Ok(decoded)
72}
73
74/// Trait for encoding using a serializer.
75pub trait Encode {
76    /// Encode self into the serializer.
77    fn encode(&self, ser: &mut Serializer) -> Result<()>;
78}
79
80/// Trait for decoding using a deserializer.
81pub trait Decode {
82    /// Decode from the deserializer into self.
83    fn decode(&mut self, de: &mut Deserializer) -> Result<()>;
84}
85
86#[cfg(test)]
87mod tests {
88    use super::*;
89    use anyhow::Result;
90    use serde::{Deserialize, Serialize};
91    use std::collections::HashMap;
92
93    #[test]
94    fn serde_unit() -> Result<()> {
95        let val = ();
96        let buffer = to_vec(&val, Default::default())?;
97        let res: () = from_vec(buffer, Default::default())?;
98        assert_eq!(val, res);
99        Ok(())
100    }
101
102    #[test]
103    fn serde_option_none() -> Result<()> {
104        let val: Option<u8> = None;
105        let buffer = to_vec(&val, Default::default())?;
106        let res: Option<u8> = from_vec(buffer, Default::default())?;
107        assert_eq!(val, res);
108        Ok(())
109    }
110
111    #[test]
112    fn serde_option_some() -> Result<()> {
113        let val = Some(1u8);
114        let buffer = to_vec(&val, Default::default())?;
115        let res: Option<u8> = from_vec(buffer, Default::default())?;
116        assert_eq!(val, res);
117        Ok(())
118    }
119
120    #[test]
121    fn serde_string() -> Result<()> {
122        let val = String::from("foo");
123        let buffer = to_vec(&val, Default::default())?;
124        let res: String = from_vec(buffer, Default::default())?;
125        assert_eq!(val, res);
126        Ok(())
127    }
128
129    #[test]
130    fn serde_char() -> Result<()> {
131        let val = 'x';
132        let buffer = to_vec(&val, Default::default())?;
133        let res: char = from_vec(buffer, Default::default())?;
134        assert_eq!(val, res);
135        Ok(())
136    }
137
138    #[test]
139    fn serde_bool_true() -> Result<()> {
140        let val = true;
141        let buffer = to_vec(&val, Default::default())?;
142        let res: bool = from_vec(buffer, Default::default())?;
143        assert_eq!(val, res);
144        Ok(())
145    }
146
147    #[test]
148    fn serde_bool_false() -> Result<()> {
149        let val = false;
150        let buffer = to_vec(&val, Default::default())?;
151        let res: bool = from_vec(buffer, Default::default())?;
152        assert_eq!(val, res);
153        Ok(())
154    }
155
156    #[test]
157    fn serde_u8() -> Result<()> {
158        let val = 8u8;
159        let buffer = to_vec(&val, Default::default())?;
160        let res: u8 = from_vec(buffer, Default::default())?;
161        assert_eq!(val, res);
162        Ok(())
163    }
164
165    #[test]
166    fn serde_u16() -> Result<()> {
167        let val = 16u16;
168        let buffer = to_vec(&val, Default::default())?;
169        let res: u16 = from_vec(buffer, Default::default())?;
170        assert_eq!(val, res);
171        Ok(())
172    }
173
174    #[test]
175    fn serde_u32() -> Result<()> {
176        let val = 32u32;
177        let buffer = to_vec(&val, Default::default())?;
178        let res: u32 = from_vec(buffer, Default::default())?;
179        assert_eq!(val, res);
180        Ok(())
181    }
182
183    #[test]
184    fn serde_u64() -> Result<()> {
185        let val = 64u64;
186        let buffer = to_vec(&val, Default::default())?;
187        let res: u64 = from_vec(buffer, Default::default())?;
188        assert_eq!(val, res);
189        Ok(())
190    }
191
192    #[test]
193    fn serde_usize() -> Result<()> {
194        let val = usize::MAX;
195        let buffer = to_vec(&val, Default::default())?;
196        let res: usize = from_vec(buffer, Default::default())?;
197        assert_eq!(val, res);
198        Ok(())
199    }
200
201    #[test]
202    fn serde_i8() -> Result<()> {
203        let val = -8i8;
204        let buffer = to_vec(&val, Default::default())?;
205        let res: i8 = from_vec(buffer, Default::default())?;
206        assert_eq!(val, res);
207        Ok(())
208    }
209
210    #[test]
211    fn serde_i16() -> Result<()> {
212        let val = -16i16;
213        let buffer = to_vec(&val, Default::default())?;
214        let res: i16 = from_vec(buffer, Default::default())?;
215        assert_eq!(val, res);
216        Ok(())
217    }
218
219    #[test]
220    fn serde_i32() -> Result<()> {
221        let val = -32i32;
222        let buffer = to_vec(&val, Default::default())?;
223        let res: i32 = from_vec(buffer, Default::default())?;
224        assert_eq!(val, res);
225        Ok(())
226    }
227
228    #[test]
229    fn serde_i64() -> Result<()> {
230        let val = -64i64;
231        let buffer = to_vec(&val, Default::default())?;
232        let res: i64 = from_vec(buffer, Default::default())?;
233        assert_eq!(val, res);
234        Ok(())
235    }
236
237    #[test]
238    fn serde_isize() -> Result<()> {
239        let val = isize::MIN;
240        let buffer = to_vec(&val, Default::default())?;
241        let res: isize = from_vec(buffer, Default::default())?;
242        assert_eq!(val, res);
243        Ok(())
244    }
245
246    #[test]
247    fn serde_vec() -> Result<()> {
248        let val = vec![1u8, 2u8, 3u8];
249        let buffer = to_vec(&val, Default::default())?;
250        let res: Vec<u8> = from_vec(buffer, Default::default())?;
251        assert_eq!(val, res);
252        Ok(())
253    }
254
255    #[test]
256    fn serde_tuple() -> Result<()> {
257        let val = (1u8, String::from("foo"));
258        let buffer = to_vec(&val, Default::default())?;
259        let res: (u8, String) = from_vec(buffer, Default::default())?;
260        assert_eq!(val, res);
261        Ok(())
262    }
263
264    #[test]
265    fn serde_map() -> Result<()> {
266        let mut val = HashMap::new();
267        val.insert("foo".to_string(), 1u8);
268        val.insert("bar".to_string(), 2u8);
269        let buffer = to_vec(&val, Default::default())?;
270        let res: HashMap<String, u8> = from_vec(buffer, Default::default())?;
271        assert_eq!(val, res);
272        Ok(())
273    }
274
275    #[derive(Debug, Serialize, Deserialize, Eq, PartialEq)]
276    struct SimpleStruct {
277        x: u32,
278        y: u32,
279    }
280
281    #[test]
282    fn serde_struct() -> Result<()> {
283        let val = SimpleStruct { x: 1, y: 2 };
284        let buffer = to_vec(&val, Default::default())?;
285        let res: SimpleStruct = from_vec(buffer, Default::default())?;
286        assert_eq!(val, res);
287        Ok(())
288    }
289
290    #[derive(Serialize, Deserialize, PartialEq, Debug)]
291    enum E {
292        Unit,
293        NewType(u32),
294        Tuple(u32, u32),
295        Struct { a: u32 },
296    }
297
298    #[test]
299    fn serde_enum_unit() -> Result<()> {
300        let val = E::Unit;
301        let buffer = to_vec(&val, Default::default())?;
302        let res: E = from_vec(buffer, Default::default())?;
303        assert_eq!(val, res);
304        Ok(())
305    }
306
307    #[test]
308    fn serde_enum_newtype() -> Result<()> {
309        let val = E::NewType(1);
310        let buffer = to_vec(&val, Default::default())?;
311        let res: E = from_vec(buffer, Default::default())?;
312        assert_eq!(val, res);
313        Ok(())
314    }
315
316    #[test]
317    fn serde_enum_tuple() -> Result<()> {
318        let val = E::Tuple(1, 2);
319        let buffer = to_vec(&val, Default::default())?;
320        let res: E = from_vec(buffer, Default::default())?;
321        assert_eq!(val, res);
322        Ok(())
323    }
324
325    #[test]
326    fn serde_enum_struct() -> Result<()> {
327        let val = E::Struct { a: 1 };
328        let buffer = to_vec(&val, Default::default())?;
329        let res: E = from_vec(buffer, Default::default())?;
330        assert_eq!(val, res);
331        Ok(())
332    }
333
334    const MAGIC: [u8; 4] = [84, 79, 68, 79];
335
336    #[derive(Debug, Eq, PartialEq)]
337    struct TodoList {
338        magic: [u8; 4],
339        todos: Vec<Todo>,
340    }
341
342    impl Default for TodoList {
343        fn default() -> Self {
344            Self {
345                magic: MAGIC,
346                todos: vec![],
347            }
348        }
349    }
350
351    impl Encode for TodoList {
352        fn encode(&self, ser: &mut Serializer) -> super::Result<()> {
353            ser.writer.write_bytes(self.magic)?;
354            self.todos.serialize(ser)?;
355            Ok(())
356        }
357    }
358
359    impl Decode for TodoList {
360        fn decode(&mut self, de: &mut Deserializer) -> super::Result<()> {
361            self.magic = de.reader.read_bytes(4)?.as_slice().try_into()?;
362            if self.magic != MAGIC {
363                return Err(Error::Custom("not a todo list binary file".to_string()));
364            }
365
366            self.todos = Deserialize::deserialize(de)?;
367            Ok(())
368        }
369    }
370
371    #[derive(Serialize, Deserialize, Debug, Eq, PartialEq)]
372    struct Todo {
373        name: String,
374        note: String,
375    }
376
377    #[test]
378    fn serde_mixed() -> Result<()> {
379        let todos = vec![Todo {
380            name: String::from("foo"),
381            note: String::from("bar"),
382        }];
383
384        let list = TodoList {
385            magic: [84, 79, 68, 79],
386            todos,
387        };
388
389        let buffer = encode(&list, Default::default())?;
390        let decoded: TodoList = decode(&buffer, Default::default())?;
391        assert_eq!(list, decoded);
392        Ok(())
393    }
394}
serde_binary/lib.rs

serde_binary/
lib.rs
