winter_utils/serde/
mod.rs

1// Copyright (c) Facebook, Inc. and its affiliates.
2//
3// This source code is licensed under the MIT license found in the
4// LICENSE file in the root directory of this source tree.
5
6use alloc::{
7    collections::{BTreeMap, BTreeSet},
8    string::String,
9    vec::Vec,
10};
11
12use super::DeserializationError;
13
14mod byte_reader;
15#[cfg(feature = "std")]
16pub use byte_reader::ReadAdapter;
17pub use byte_reader::{ByteReader, SliceReader};
18
19mod byte_writer;
20pub use byte_writer::ByteWriter;
21
22// SERIALIZABLE TRAIT
23// ================================================================================================
24
25/// Defines how to serialize `Self` into bytes.
26pub trait Serializable {
27    // REQUIRED METHODS
28    // --------------------------------------------------------------------------------------------
29    /// Serializes `self` into bytes and writes these bytes into the `target`.
30    fn write_into<W: ByteWriter>(&self, target: &mut W);
31
32    // PROVIDED METHODS
33    // --------------------------------------------------------------------------------------------
34
35    /// Serializes `self` into a vector of bytes.
36    fn to_bytes(&self) -> Vec<u8> {
37        let mut result = Vec::with_capacity(self.get_size_hint());
38        self.write_into(&mut result);
39        result
40    }
41
42    /// Returns an estimate of how many bytes are needed to represent self.
43    ///
44    /// The default implementation returns zero.
45    fn get_size_hint(&self) -> usize {
46        0
47    }
48}
49
50impl<T: Serializable> Serializable for &T {
51    fn write_into<W: ByteWriter>(&self, target: &mut W) {
52        (*self).write_into(target)
53    }
54
55    fn get_size_hint(&self) -> usize {
56        (*self).get_size_hint()
57    }
58}
59
60impl Serializable for () {
61    fn write_into<W: ByteWriter>(&self, _target: &mut W) {}
62
63    fn get_size_hint(&self) -> usize {
64        0
65    }
66}
67
68impl<T1> Serializable for (T1,)
69where
70    T1: Serializable,
71{
72    fn write_into<W: ByteWriter>(&self, target: &mut W) {
73        self.0.write_into(target);
74    }
75
76    fn get_size_hint(&self) -> usize {
77        self.0.get_size_hint()
78    }
79}
80
81impl<T1, T2> Serializable for (T1, T2)
82where
83    T1: Serializable,
84    T2: Serializable,
85{
86    fn write_into<W: ByteWriter>(&self, target: &mut W) {
87        self.0.write_into(target);
88        self.1.write_into(target);
89    }
90
91    fn get_size_hint(&self) -> usize {
92        self.0.get_size_hint() + self.1.get_size_hint()
93    }
94}
95
96impl<T1, T2, T3> Serializable for (T1, T2, T3)
97where
98    T1: Serializable,
99    T2: Serializable,
100    T3: Serializable,
101{
102    fn write_into<W: ByteWriter>(&self, target: &mut W) {
103        self.0.write_into(target);
104        self.1.write_into(target);
105        self.2.write_into(target);
106    }
107
108    fn get_size_hint(&self) -> usize {
109        self.0.get_size_hint() + self.1.get_size_hint() + self.2.get_size_hint()
110    }
111}
112
113impl<T1, T2, T3, T4> Serializable for (T1, T2, T3, T4)
114where
115    T1: Serializable,
116    T2: Serializable,
117    T3: Serializable,
118    T4: Serializable,
119{
120    fn write_into<W: ByteWriter>(&self, target: &mut W) {
121        self.0.write_into(target);
122        self.1.write_into(target);
123        self.2.write_into(target);
124        self.3.write_into(target);
125    }
126
127    fn get_size_hint(&self) -> usize {
128        self.0.get_size_hint()
129            + self.1.get_size_hint()
130            + self.2.get_size_hint()
131            + self.3.get_size_hint()
132    }
133}
134
135impl<T1, T2, T3, T4, T5> Serializable for (T1, T2, T3, T4, T5)
136where
137    T1: Serializable,
138    T2: Serializable,
139    T3: Serializable,
140    T4: Serializable,
141    T5: Serializable,
142{
143    fn write_into<W: ByteWriter>(&self, target: &mut W) {
144        self.0.write_into(target);
145        self.1.write_into(target);
146        self.2.write_into(target);
147        self.3.write_into(target);
148        self.4.write_into(target);
149    }
150
151    fn get_size_hint(&self) -> usize {
152        self.0.get_size_hint()
153            + self.1.get_size_hint()
154            + self.2.get_size_hint()
155            + self.3.get_size_hint()
156            + self.4.get_size_hint()
157    }
158}
159
160impl<T1, T2, T3, T4, T5, T6> Serializable for (T1, T2, T3, T4, T5, T6)
161where
162    T1: Serializable,
163    T2: Serializable,
164    T3: Serializable,
165    T4: Serializable,
166    T5: Serializable,
167    T6: Serializable,
168{
169    fn write_into<W: ByteWriter>(&self, target: &mut W) {
170        self.0.write_into(target);
171        self.1.write_into(target);
172        self.2.write_into(target);
173        self.3.write_into(target);
174        self.4.write_into(target);
175        self.5.write_into(target);
176    }
177
178    fn get_size_hint(&self) -> usize {
179        self.0.get_size_hint()
180            + self.1.get_size_hint()
181            + self.2.get_size_hint()
182            + self.3.get_size_hint()
183            + self.4.get_size_hint()
184            + self.5.get_size_hint()
185    }
186}
187
188impl Serializable for u8 {
189    fn write_into<W: ByteWriter>(&self, target: &mut W) {
190        target.write_u8(*self);
191    }
192
193    fn get_size_hint(&self) -> usize {
194        core::mem::size_of::<u8>()
195    }
196}
197
198impl Serializable for u16 {
199    fn write_into<W: ByteWriter>(&self, target: &mut W) {
200        target.write_u16(*self);
201    }
202
203    fn get_size_hint(&self) -> usize {
204        core::mem::size_of::<u16>()
205    }
206}
207
208impl Serializable for u32 {
209    fn write_into<W: ByteWriter>(&self, target: &mut W) {
210        target.write_u32(*self);
211    }
212
213    fn get_size_hint(&self) -> usize {
214        core::mem::size_of::<u32>()
215    }
216}
217
218impl Serializable for u64 {
219    fn write_into<W: ByteWriter>(&self, target: &mut W) {
220        target.write_u64(*self);
221    }
222
223    fn get_size_hint(&self) -> usize {
224        core::mem::size_of::<u64>()
225    }
226}
227
228impl Serializable for u128 {
229    fn write_into<W: ByteWriter>(&self, target: &mut W) {
230        target.write_u128(*self);
231    }
232
233    fn get_size_hint(&self) -> usize {
234        core::mem::size_of::<u128>()
235    }
236}
237
238impl Serializable for usize {
239    fn write_into<W: ByteWriter>(&self, target: &mut W) {
240        target.write_usize(*self)
241    }
242
243    fn get_size_hint(&self) -> usize {
244        byte_writer::usize_encoded_len(*self as u64)
245    }
246}
247
248impl<T: Serializable> Serializable for Option<T> {
249    fn write_into<W: ByteWriter>(&self, target: &mut W) {
250        match self {
251            Some(v) => {
252                target.write_bool(true);
253                v.write_into(target);
254            },
255            None => target.write_bool(false),
256        }
257    }
258
259    fn get_size_hint(&self) -> usize {
260        core::mem::size_of::<bool>() + self.as_ref().map(|value| value.get_size_hint()).unwrap_or(0)
261    }
262}
263
264impl<T: Serializable, const C: usize> Serializable for [T; C] {
265    fn write_into<W: ByteWriter>(&self, target: &mut W) {
266        target.write_many(self)
267    }
268
269    fn get_size_hint(&self) -> usize {
270        let mut size = 0;
271        for item in self {
272            size += item.get_size_hint();
273        }
274        size
275    }
276}
277
278impl<T: Serializable> Serializable for [T] {
279    fn write_into<W: ByteWriter>(&self, target: &mut W) {
280        target.write_usize(self.len());
281        for element in self.iter() {
282            element.write_into(target);
283        }
284    }
285
286    fn get_size_hint(&self) -> usize {
287        let mut size = self.len().get_size_hint();
288        for element in self {
289            size += element.get_size_hint();
290        }
291        size
292    }
293}
294
295impl<T: Serializable> Serializable for Vec<T> {
296    fn write_into<W: ByteWriter>(&self, target: &mut W) {
297        target.write_usize(self.len());
298        target.write_many(self);
299    }
300
301    fn get_size_hint(&self) -> usize {
302        let mut size = self.len().get_size_hint();
303        for item in self {
304            size += item.get_size_hint();
305        }
306        size
307    }
308}
309
310impl<K: Serializable, V: Serializable> Serializable for BTreeMap<K, V> {
311    fn write_into<W: ByteWriter>(&self, target: &mut W) {
312        target.write_usize(self.len());
313        target.write_many(self);
314    }
315
316    fn get_size_hint(&self) -> usize {
317        let mut size = self.len().get_size_hint();
318        for item in self {
319            size += item.get_size_hint();
320        }
321        size
322    }
323}
324
325impl<T: Serializable> Serializable for BTreeSet<T> {
326    fn write_into<W: ByteWriter>(&self, target: &mut W) {
327        target.write_usize(self.len());
328        target.write_many(self);
329    }
330
331    fn get_size_hint(&self) -> usize {
332        let mut size = self.len().get_size_hint();
333        for item in self {
334            size += item.get_size_hint();
335        }
336        size
337    }
338}
339
340impl Serializable for str {
341    fn write_into<W: ByteWriter>(&self, target: &mut W) {
342        target.write_usize(self.len());
343        target.write_many(self.as_bytes());
344    }
345
346    fn get_size_hint(&self) -> usize {
347        self.len().get_size_hint() + self.len()
348    }
349}
350
351impl Serializable for String {
352    fn write_into<W: ByteWriter>(&self, target: &mut W) {
353        target.write_usize(self.len());
354        target.write_many(self.as_bytes());
355    }
356
357    fn get_size_hint(&self) -> usize {
358        self.len().get_size_hint() + self.len()
359    }
360}
361
362// DESERIALIZABLE
363// ================================================================================================
364
365/// Defines how to deserialize `Self` from bytes.
366pub trait Deserializable: Sized {
367    // REQUIRED METHODS
368    // --------------------------------------------------------------------------------------------
369
370    /// Reads a sequence of bytes from the provided `source`, attempts to deserialize these bytes
371    /// into `Self`, and returns the result.
372    ///
373    /// # Errors
374    /// Returns an error if:
375    /// * The `source` does not contain enough bytes to deserialize `Self`.
376    /// * Bytes read from the `source` do not represent a valid value for `Self`.
377    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError>;
378
379    // PROVIDED METHODS
380    // --------------------------------------------------------------------------------------------
381
382    /// Attempts to deserialize the provided `bytes` into `Self` and returns the result.
383    ///
384    /// # Errors
385    /// Returns an error if:
386    /// * The `bytes` do not contain enough information to deserialize `Self`.
387    /// * The `bytes` do not represent a valid value for `Self`.
388    ///
389    /// Note: if `bytes` contains more data than needed to deserialize `self`, no error is
390    /// returned.
391    fn read_from_bytes(bytes: &[u8]) -> Result<Self, DeserializationError> {
392        Self::read_from(&mut SliceReader::new(bytes))
393    }
394}
395
396impl Deserializable for () {
397    fn read_from<R: ByteReader>(_source: &mut R) -> Result<Self, DeserializationError> {
398        Ok(())
399    }
400}
401
402impl<T1> Deserializable for (T1,)
403where
404    T1: Deserializable,
405{
406    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
407        let v1 = T1::read_from(source)?;
408        Ok((v1,))
409    }
410}
411
412impl<T1, T2> Deserializable for (T1, T2)
413where
414    T1: Deserializable,
415    T2: Deserializable,
416{
417    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
418        let v1 = T1::read_from(source)?;
419        let v2 = T2::read_from(source)?;
420        Ok((v1, v2))
421    }
422}
423
424impl<T1, T2, T3> Deserializable for (T1, T2, T3)
425where
426    T1: Deserializable,
427    T2: Deserializable,
428    T3: Deserializable,
429{
430    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
431        let v1 = T1::read_from(source)?;
432        let v2 = T2::read_from(source)?;
433        let v3 = T3::read_from(source)?;
434        Ok((v1, v2, v3))
435    }
436}
437
438impl<T1, T2, T3, T4> Deserializable for (T1, T2, T3, T4)
439where
440    T1: Deserializable,
441    T2: Deserializable,
442    T3: Deserializable,
443    T4: Deserializable,
444{
445    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
446        let v1 = T1::read_from(source)?;
447        let v2 = T2::read_from(source)?;
448        let v3 = T3::read_from(source)?;
449        let v4 = T4::read_from(source)?;
450        Ok((v1, v2, v3, v4))
451    }
452}
453
454impl<T1, T2, T3, T4, T5> Deserializable for (T1, T2, T3, T4, T5)
455where
456    T1: Deserializable,
457    T2: Deserializable,
458    T3: Deserializable,
459    T4: Deserializable,
460    T5: Deserializable,
461{
462    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
463        let v1 = T1::read_from(source)?;
464        let v2 = T2::read_from(source)?;
465        let v3 = T3::read_from(source)?;
466        let v4 = T4::read_from(source)?;
467        let v5 = T5::read_from(source)?;
468        Ok((v1, v2, v3, v4, v5))
469    }
470}
471
472impl<T1, T2, T3, T4, T5, T6> Deserializable for (T1, T2, T3, T4, T5, T6)
473where
474    T1: Deserializable,
475    T2: Deserializable,
476    T3: Deserializable,
477    T4: Deserializable,
478    T5: Deserializable,
479    T6: Deserializable,
480{
481    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
482        let v1 = T1::read_from(source)?;
483        let v2 = T2::read_from(source)?;
484        let v3 = T3::read_from(source)?;
485        let v4 = T4::read_from(source)?;
486        let v5 = T5::read_from(source)?;
487        let v6 = T6::read_from(source)?;
488        Ok((v1, v2, v3, v4, v5, v6))
489    }
490}
491
492impl Deserializable for u8 {
493    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
494        source.read_u8()
495    }
496}
497
498impl Deserializable for u16 {
499    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
500        source.read_u16()
501    }
502}
503
504impl Deserializable for u32 {
505    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
506        source.read_u32()
507    }
508}
509
510impl Deserializable for u64 {
511    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
512        source.read_u64()
513    }
514}
515
516impl Deserializable for u128 {
517    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
518        source.read_u128()
519    }
520}
521
522impl Deserializable for usize {
523    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
524        source.read_usize()
525    }
526}
527
528impl<T: Deserializable> Deserializable for Option<T> {
529    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
530        let contains = source.read_bool()?;
531
532        match contains {
533            true => Ok(Some(T::read_from(source)?)),
534            false => Ok(None),
535        }
536    }
537}
538
539impl<T: Deserializable, const C: usize> Deserializable for [T; C] {
540    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
541        let data: Vec<T> = source.read_many(C)?;
542
543        // SAFETY: the call above only returns a Vec if there are `C` elements, this conversion
544        // always succeeds
545        let res = data.try_into().unwrap_or_else(|v: Vec<T>| {
546            panic!("Expected a Vec of length {} but it was {}", C, v.len())
547        });
548
549        Ok(res)
550    }
551}
552
553impl<T: Deserializable> Deserializable for Vec<T> {
554    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
555        let len = source.read_usize()?;
556        source.read_many(len)
557    }
558}
559
560impl<K: Deserializable + Ord, V: Deserializable> Deserializable for BTreeMap<K, V> {
561    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
562        let len = source.read_usize()?;
563        let data = source.read_many(len)?;
564        Ok(BTreeMap::from_iter(data))
565    }
566}
567
568impl<T: Deserializable + Ord> Deserializable for BTreeSet<T> {
569    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
570        let len = source.read_usize()?;
571        let data = source.read_many(len)?;
572        Ok(BTreeSet::from_iter(data))
573    }
574}
575
576impl Deserializable for String {
577    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
578        let len = source.read_usize()?;
579        let data = source.read_many(len)?;
580
581        String::from_utf8(data)
582            .map_err(|err| DeserializationError::InvalidValue(format!("{}", err)))
583    }
584}
winter_utils/serde/mod.rs

winter_utils/serde/
mod.rs
