postcard/ser/
serializer.rs

1use serde::{ser, Serialize};
2
3use crate::error::{Error, Result};
4use crate::ser::flavors::Flavor;
5use crate::varint::*;
6
7/// A `serde` compatible serializer, generic over "Flavors" of serializing plugins.
8///
9/// It should rarely be necessary to directly use this type unless you are implementing your
10/// own [`SerFlavor`].
11///
12/// See the docs for [`SerFlavor`] for more information about "flavors" of serialization
13///
14/// [`SerFlavor`]: crate::ser_flavors::Flavor
15pub struct Serializer<F>
16where
17    F: Flavor,
18{
19    /// This is the Flavor(s) that will be used to modify or store any bytes generated
20    /// by serialization
21    pub output: F,
22}
23
24impl<F: Flavor> Serializer<F> {
25    /// Attempt to push a variably encoded [usize] into the output data stream
26    #[inline]
27    pub(crate) fn try_push_varint_usize(&mut self, data: usize) -> Result<()> {
28        let mut buf = [0u8; varint_max::<usize>()];
29        let used_buf = varint_usize(data, &mut buf);
30        self.output.try_extend(used_buf)
31    }
32
33    /// Attempt to push a variably encoded [u128] into the output data stream
34    #[inline]
35    pub(crate) fn try_push_varint_u128(&mut self, data: u128) -> Result<()> {
36        let mut buf = [0u8; varint_max::<u128>()];
37        let used_buf = varint_u128(data, &mut buf);
38        self.output.try_extend(used_buf)
39    }
40
41    /// Attempt to push a variably encoded [u64] into the output data stream
42    #[inline]
43    pub(crate) fn try_push_varint_u64(&mut self, data: u64) -> Result<()> {
44        let mut buf = [0u8; varint_max::<u64>()];
45        let used_buf = varint_u64(data, &mut buf);
46        self.output.try_extend(used_buf)
47    }
48
49    /// Attempt to push a variably encoded [u32] into the output data stream
50    #[inline]
51    pub(crate) fn try_push_varint_u32(&mut self, data: u32) -> Result<()> {
52        let mut buf = [0u8; varint_max::<u32>()];
53        let used_buf = varint_u32(data, &mut buf);
54        self.output.try_extend(used_buf)
55    }
56
57    /// Attempt to push a variably encoded [u16] into the output data stream
58    #[inline]
59    pub(crate) fn try_push_varint_u16(&mut self, data: u16) -> Result<()> {
60        let mut buf = [0u8; varint_max::<u16>()];
61        let used_buf = varint_u16(data, &mut buf);
62        self.output.try_extend(used_buf)
63    }
64}
65
66impl<'a, F> ser::Serializer for &'a mut Serializer<F>
67where
68    F: Flavor,
69{
70    type Ok = ();
71
72    type Error = Error;
73
74    // Associated types for keeping track of additional state while serializing
75    // compound data structures like sequences and maps. In this case no
76    // additional state is required beyond what is already stored in the
77    // Serializer struct.
78    type SerializeSeq = Self;
79    type SerializeTuple = Self;
80    type SerializeTupleStruct = SerializeTupleStruct<'a, F>;
81    type SerializeTupleVariant = Self;
82    type SerializeMap = Self;
83    type SerializeStruct = Self;
84    type SerializeStructVariant = Self;
85
86    #[inline]
87    fn is_human_readable(&self) -> bool {
88        false
89    }
90
91    #[inline]
92    fn serialize_bool(self, v: bool) -> Result<()> {
93        self.serialize_u8(if v { 1 } else { 0 })
94    }
95
96    #[inline]
97    fn serialize_i8(self, v: i8) -> Result<()> {
98        self.serialize_u8(v.to_le_bytes()[0])
99    }
100
101    #[inline]
102    fn serialize_i16(self, v: i16) -> Result<()> {
103        let zzv = zig_zag_i16(v);
104        self.try_push_varint_u16(zzv)
105            .map_err(|_| Error::SerializeBufferFull)
106    }
107
108    #[inline]
109    fn serialize_i32(self, v: i32) -> Result<()> {
110        let zzv = zig_zag_i32(v);
111        self.try_push_varint_u32(zzv)
112            .map_err(|_| Error::SerializeBufferFull)
113    }
114
115    #[inline]
116    fn serialize_i64(self, v: i64) -> Result<()> {
117        let zzv = zig_zag_i64(v);
118        self.try_push_varint_u64(zzv)
119            .map_err(|_| Error::SerializeBufferFull)
120    }
121
122    #[inline]
123    fn serialize_i128(self, v: i128) -> Result<()> {
124        let zzv = zig_zag_i128(v);
125        self.try_push_varint_u128(zzv)
126            .map_err(|_| Error::SerializeBufferFull)
127    }
128
129    #[inline]
130    fn serialize_u8(self, v: u8) -> Result<()> {
131        self.output
132            .try_push(v)
133            .map_err(|_| Error::SerializeBufferFull)
134    }
135
136    #[inline]
137    fn serialize_u16(self, v: u16) -> Result<()> {
138        self.try_push_varint_u16(v)
139            .map_err(|_| Error::SerializeBufferFull)
140    }
141
142    #[inline]
143    fn serialize_u32(self, v: u32) -> Result<()> {
144        self.try_push_varint_u32(v)
145            .map_err(|_| Error::SerializeBufferFull)
146    }
147
148    #[inline]
149    fn serialize_u64(self, v: u64) -> Result<()> {
150        self.try_push_varint_u64(v)
151            .map_err(|_| Error::SerializeBufferFull)
152    }
153
154    #[inline]
155    fn serialize_u128(self, v: u128) -> Result<()> {
156        self.try_push_varint_u128(v)
157            .map_err(|_| Error::SerializeBufferFull)
158    }
159
160    #[inline]
161    fn serialize_f32(self, v: f32) -> Result<()> {
162        let buf = v.to_bits().to_le_bytes();
163        self.output
164            .try_extend(&buf)
165            .map_err(|_| Error::SerializeBufferFull)
166    }
167
168    #[inline]
169    fn serialize_f64(self, v: f64) -> Result<()> {
170        let buf = v.to_bits().to_le_bytes();
171        self.output
172            .try_extend(&buf)
173            .map_err(|_| Error::SerializeBufferFull)
174    }
175
176    #[inline]
177    fn serialize_char(self, v: char) -> Result<()> {
178        let mut buf = [0u8; 4];
179        let strsl = v.encode_utf8(&mut buf);
180        strsl.serialize(self)
181    }
182
183    #[inline]
184    fn serialize_str(self, v: &str) -> Result<()> {
185        self.try_push_varint_usize(v.len())
186            .map_err(|_| Error::SerializeBufferFull)?;
187        self.output
188            .try_extend(v.as_bytes())
189            .map_err(|_| Error::SerializeBufferFull)?;
190        Ok(())
191    }
192
193    #[inline]
194    fn serialize_bytes(self, v: &[u8]) -> Result<()> {
195        self.try_push_varint_usize(v.len())
196            .map_err(|_| Error::SerializeBufferFull)?;
197        self.output
198            .try_extend(v)
199            .map_err(|_| Error::SerializeBufferFull)
200    }
201
202    #[inline]
203    fn serialize_none(self) -> Result<()> {
204        self.serialize_u8(0)
205    }
206
207    #[inline]
208    fn serialize_some<T>(self, value: &T) -> Result<()>
209    where
210        T: ?Sized + Serialize,
211    {
212        self.serialize_u8(1)?;
213        value.serialize(self)
214    }
215
216    #[inline]
217    fn serialize_unit(self) -> Result<()> {
218        Ok(())
219    }
220
221    #[inline]
222    fn serialize_unit_struct(self, _name: &'static str) -> Result<()> {
223        Ok(())
224    }
225
226    #[inline]
227    fn serialize_unit_variant(
228        self,
229        _name: &'static str,
230        variant_index: u32,
231        _variant: &'static str,
232    ) -> Result<()> {
233        self.try_push_varint_u32(variant_index)
234            .map_err(|_| Error::SerializeBufferFull)
235    }
236
237    #[inline]
238    fn serialize_newtype_struct<T>(self, _name: &'static str, value: &T) -> Result<()>
239    where
240        T: ?Sized + Serialize,
241    {
242        value.serialize(self)
243    }
244
245    #[inline]
246    fn serialize_newtype_variant<T>(
247        self,
248        _name: &'static str,
249        variant_index: u32,
250        _variant: &'static str,
251        value: &T,
252    ) -> Result<()>
253    where
254        T: ?Sized + Serialize,
255    {
256        self.try_push_varint_u32(variant_index)
257            .map_err(|_| Error::SerializeBufferFull)?;
258        value.serialize(self)
259    }
260
261    #[inline]
262    fn serialize_seq(self, len: Option<usize>) -> Result<Self::SerializeSeq> {
263        self.try_push_varint_usize(len.ok_or(Error::SerializeSeqLengthUnknown)?)
264            .map_err(|_| Error::SerializeBufferFull)?;
265        Ok(self)
266    }
267
268    #[inline]
269    fn serialize_tuple(self, _len: usize) -> Result<Self::SerializeTuple> {
270        Ok(self)
271    }
272
273    #[inline]
274    fn serialize_tuple_struct(
275        self,
276        name: &'static str,
277        _len: usize,
278    ) -> Result<Self::SerializeTupleStruct> {
279        Ok(if name.as_ptr() == crate::byte_array::TOKEN.as_ptr() {
280            SerializeTupleStruct::ByteArray { ser: self }
281        } else {
282            SerializeTupleStruct::TupleStruct { ser: self }
283        })
284    }
285
286    #[inline]
287    fn serialize_tuple_variant(
288        self,
289        _name: &'static str,
290        variant_index: u32,
291        _variant: &'static str,
292        _len: usize,
293    ) -> Result<Self::SerializeTupleVariant> {
294        self.try_push_varint_u32(variant_index)
295            .map_err(|_| Error::SerializeBufferFull)?;
296        Ok(self)
297    }
298
299    #[inline]
300    fn serialize_map(self, len: Option<usize>) -> Result<Self::SerializeMap> {
301        self.try_push_varint_usize(len.ok_or(Error::SerializeSeqLengthUnknown)?)
302            .map_err(|_| Error::SerializeBufferFull)?;
303        Ok(self)
304    }
305
306    #[inline]
307    fn serialize_struct(self, _name: &'static str, _len: usize) -> Result<Self::SerializeStruct> {
308        Ok(self)
309    }
310
311    #[inline]
312    fn serialize_struct_variant(
313        self,
314        _name: &'static str,
315        variant_index: u32,
316        _variant: &'static str,
317        _len: usize,
318    ) -> Result<Self::SerializeStructVariant> {
319        self.try_push_varint_u32(variant_index)
320            .map_err(|_| Error::SerializeBufferFull)?;
321        Ok(self)
322    }
323
324    #[inline]
325    fn collect_str<T>(self, value: &T) -> Result<Self::Ok>
326    where
327        T: core::fmt::Display + ?Sized,
328    {
329        use core::fmt::Write;
330
331        // Unfortunately, we need to know the size of the serialized data before
332        // we can place it into the output. In order to do this, we run the formatting
333        // of the output data TWICE, the first time to determine the length, the
334        // second time to actually format the data
335        //
336        // There are potentially other ways to do this, such as:
337        //
338        // * Reserving a fixed max size, such as 5 bytes, for the length field, and
339        //     leaving non-canonical trailing zeroes at the end. This would work up
340        //     to some reasonable length, but might have some portability vs max size
341        //     tradeoffs, e.g. 64KiB if we pick 3 bytes, or 4GiB if we pick 5 bytes
342        // * Expose some kind of "memmove" capability to flavors, to allow us to
343        //     format into the buffer, then "scoot over" that many times.
344        //
345        // Despite the current approaches downside in speed, it is likely flexible
346        // enough for the rare-ish case where formatting a Debug impl is necessary.
347        // This is better than the previous panicking behavior, and can be improved
348        // in the future.
349        struct CountWriter {
350            ct: usize,
351        }
352        impl Write for CountWriter {
353            fn write_str(&mut self, s: &str) -> core::result::Result<(), core::fmt::Error> {
354                self.ct += s.len();
355                Ok(())
356            }
357        }
358
359        let mut ctr = CountWriter { ct: 0 };
360
361        // This is the first pass through, where we just count the length of the
362        // data that we are given
363        write!(&mut ctr, "{value}").map_err(|_| Error::CollectStrError)?;
364        let len = ctr.ct;
365        self.try_push_varint_usize(len)
366            .map_err(|_| Error::SerializeBufferFull)?;
367
368        struct FmtWriter<'a, IF>
369        where
370            IF: Flavor,
371        {
372            output: &'a mut IF,
373        }
374        impl<IF> Write for FmtWriter<'_, IF>
375        where
376            IF: Flavor,
377        {
378            fn write_str(&mut self, s: &str) -> core::result::Result<(), core::fmt::Error> {
379                self.output
380                    .try_extend(s.as_bytes())
381                    .map_err(|_| core::fmt::Error)
382            }
383        }
384
385        // This second pass actually inserts the data.
386        let mut fw = FmtWriter {
387            output: &mut self.output,
388        };
389        write!(&mut fw, "{value}").map_err(|_| Error::CollectStrError)?;
390
391        Ok(())
392    }
393}
394
395impl<F> ser::SerializeSeq for &mut Serializer<F>
396where
397    F: Flavor,
398{
399    // Must match the `Ok` type of the serializer.
400    type Ok = ();
401    // Must match the `Error` type of the serializer.
402    type Error = Error;
403
404    // Serialize a single element of the sequence.
405    #[inline]
406    fn serialize_element<T>(&mut self, value: &T) -> Result<()>
407    where
408        T: ?Sized + Serialize,
409    {
410        value.serialize(&mut **self)
411    }
412
413    // Close the sequence.
414    #[inline]
415    fn end(self) -> Result<()> {
416        Ok(())
417    }
418}
419
420impl<F> ser::SerializeTuple for &mut Serializer<F>
421where
422    F: Flavor,
423{
424    type Ok = ();
425    type Error = Error;
426
427    #[inline]
428    fn serialize_element<T>(&mut self, value: &T) -> Result<()>
429    where
430        T: ?Sized + Serialize,
431    {
432        value.serialize(&mut **self)
433    }
434
435    #[inline]
436    fn end(self) -> Result<()> {
437        Ok(())
438    }
439}
440
441struct FixedSizeByteArrayEmitter<'a, F>(&'a mut Serializer<F>) where F: Flavor;
442
443impl<'a, F: Flavor> ser::Serializer for FixedSizeByteArrayEmitter<'a, F> {
444    type Ok = ();
445    type Error = Error;
446
447    type SerializeSeq = ser::Impossible<(), Error>;
448    type SerializeTuple = ser::Impossible<(), Error>;
449    type SerializeTupleStruct = ser::Impossible<(), Error>;
450    type SerializeTupleVariant = ser::Impossible<(), Error>;
451    type SerializeMap = ser::Impossible<(), Error>;
452    type SerializeStruct = ser::Impossible<(), Error>;
453    type SerializeStructVariant = ser::Impossible<(), Error>;
454
455    fn serialize_bool(self, _v: bool) -> Result<()> {
456        Err(ser::Error::custom("expected FixedSizeByteArray"))
457    }
458
459    fn serialize_i8(self, _v: i8) -> Result<()> {
460        Err(ser::Error::custom("expected FixedSizeByteArray"))
461    }
462
463    fn serialize_i16(self, _v: i16) -> Result<()> {
464        Err(ser::Error::custom("expected FixedSizeByteArray"))
465    }
466
467    fn serialize_i32(self, _v: i32) -> Result<()> {
468        Err(ser::Error::custom("expected FixedSizeByteArray"))
469    }
470
471    fn serialize_i64(self, _v: i64) -> Result<()> {
472        Err(ser::Error::custom("expected FixedSizeByteArray"))
473    }
474
475    fn serialize_i128(self, _v: i128) -> Result<()> {
476        Err(ser::Error::custom("expected FixedSizeByteArray"))
477    }
478
479    fn serialize_u8(self, _v: u8) -> Result<()> {
480        Err(ser::Error::custom("expected FixedSizeByteArray"))
481    }
482
483    fn serialize_u16(self, _v: u16) -> Result<()> {
484        Err(ser::Error::custom("expected FixedSizeByteArray"))
485    }
486
487    fn serialize_u32(self, _v: u32) -> Result<()> {
488        Err(ser::Error::custom("expected FixedSizeByteArray"))
489    }
490
491    fn serialize_u64(self, _v: u64) -> Result<()> {
492        Err(ser::Error::custom("expected FixedSizeByteArray"))
493    }
494
495    fn serialize_u128(self, _v: u128) -> Result<()> {
496        Err(ser::Error::custom("expected FixedSizeByteArray"))
497    }
498
499    fn serialize_f32(self, _v: f32) -> Result<()> {
500        Err(ser::Error::custom("expected FixedSizeByteArray"))
501    }
502
503    fn serialize_f64(self, _v: f64) -> Result<()> {
504        Err(ser::Error::custom("expected FixedSizeByteArray"))
505    }
506
507    fn serialize_char(self, _v: char) -> Result<()> {
508        Err(ser::Error::custom("expected FixedSizeByteArray"))
509    }
510
511    fn serialize_str(self, _value: &str) -> Result<()> {
512        Err(ser::Error::custom("expected FixedSizeByteArray"))
513    }
514
515    fn serialize_bytes(self, value: &[u8]) -> Result<()> {
516        let FixedSizeByteArrayEmitter(serializer) = self;
517        serializer.output.try_extend(value)
518    }
519
520    fn serialize_none(self) -> Result<()> {
521        Err(ser::Error::custom("expected FixedSizeByteArray"))
522    }
523
524    fn serialize_some<T>(self, _value: &T) -> Result<()>
525    where
526        T: ?Sized + Serialize,
527    {
528        Err(ser::Error::custom("expected FixedSizeByteArray"))
529    }
530
531    fn serialize_unit(self) -> Result<()> {
532        Err(ser::Error::custom("expected FixedSizeByteArray"))
533    }
534
535    fn serialize_unit_struct(self, _name: &'static str) -> Result<()> {
536        Err(ser::Error::custom("expected FixedSizeByteArray"))
537    }
538
539    fn serialize_unit_variant(
540        self,
541        _name: &'static str,
542        _variant_index: u32,
543        _variant: &'static str,
544    ) -> Result<()> {
545        Err(ser::Error::custom("expected FixedSizeByteArray"))
546    }
547
548    fn serialize_newtype_struct<T>(self, _name: &'static str, _value: &T) -> Result<()>
549    where
550        T: ?Sized + Serialize,
551    {
552        Err(ser::Error::custom("expected FixedSizeByteArray"))
553    }
554
555    fn serialize_newtype_variant<T>(
556        self,
557        _name: &'static str,
558        _variant_index: u32,
559        _variant: &'static str,
560        _value: &T,
561    ) -> Result<()>
562    where
563        T: ?Sized + Serialize,
564    {
565        Err(ser::Error::custom("expected FixedSizeByteArray"))
566    }
567
568    fn serialize_seq(self, _len: Option<usize>) -> Result<Self::SerializeSeq> {
569        Err(ser::Error::custom("expected FixedSizeByteArray"))
570    }
571
572    fn serialize_tuple(self, _len: usize) -> Result<Self::SerializeTuple> {
573        Err(ser::Error::custom("expected FixedSizeByteArray"))
574    }
575
576    fn serialize_tuple_struct(
577        self,
578        _name: &'static str,
579        _len: usize,
580    ) -> Result<Self::SerializeTupleStruct> {
581        Err(ser::Error::custom("expected FixedSizeByteArray"))
582    }
583
584    fn serialize_tuple_variant(
585        self,
586        _name: &'static str,
587        _variant_index: u32,
588        _variant: &'static str,
589        _len: usize,
590    ) -> Result<Self::SerializeTupleVariant> {
591        Err(ser::Error::custom("expected FixedSizeByteArray"))
592    }
593
594    fn serialize_map(self, _len: Option<usize>) -> Result<Self::SerializeMap> {
595        Err(ser::Error::custom("expected FixedSizeByteArray"))
596    }
597
598    fn serialize_struct(self, _name: &'static str, _len: usize) -> Result<Self::SerializeStruct> {
599        Err(ser::Error::custom("expected FixedSizeByteArray"))
600    }
601
602    fn serialize_struct_variant(
603        self,
604        _name: &'static str,
605        _variant_index: u32,
606        _variant: &'static str,
607        _len: usize,
608    ) -> Result<Self::SerializeStructVariant> {
609        Err(ser::Error::custom("expected FixedSizeByteArray"))
610    }
611
612    fn collect_str<T>(self, _value: &T) -> Result<Self::Ok>
613    where
614        T: ?Sized + core::fmt::Display,
615    {
616        Err(ser::Error::custom("expected FixedSizeByteArray"))
617    }
618}
619
620
621pub enum SerializeTupleStruct<'a, F>
622where
623    F: Flavor,
624{
625    TupleStruct {
626        ser: &'a mut Serializer<F>,
627    },
628    ByteArray {
629        ser: &'a mut Serializer<F>,
630    },
631    ByteArrayDone,
632}
633
634impl<'a, F> ser::SerializeTupleStruct for SerializeTupleStruct<'a, F>
635where
636    F: Flavor,
637{
638    type Ok = ();
639    type Error = Error;
640
641    #[inline]
642    fn serialize_field<T>(&mut self, value: &T) -> Result<()>
643    where
644        T: ?Sized + Serialize,
645    {
646        match self {
647            SerializeTupleStruct::TupleStruct { ser } => value.serialize(&mut **ser),
648            SerializeTupleStruct::ByteArray { ser } => {
649                value.serialize(FixedSizeByteArrayEmitter(&mut **ser))?;
650                *self = SerializeTupleStruct::ByteArrayDone;
651                Ok(())
652            },
653            SerializeTupleStruct::ByteArrayDone => unreachable!(),
654        }
655    }
656
657    #[inline]
658    fn end(self) -> Result<()> {
659        Ok(())
660    }
661}
662
663impl<F> ser::SerializeTupleVariant for &mut Serializer<F>
664where
665    F: Flavor,
666{
667    type Ok = ();
668    type Error = Error;
669
670    #[inline]
671    fn serialize_field<T>(&mut self, value: &T) -> Result<()>
672    where
673        T: ?Sized + Serialize,
674    {
675        value.serialize(&mut **self)
676    }
677
678    #[inline]
679    fn end(self) -> Result<()> {
680        Ok(())
681    }
682}
683
684impl<F> ser::SerializeMap for &mut Serializer<F>
685where
686    F: Flavor,
687{
688    type Ok = ();
689    type Error = Error;
690
691    #[inline]
692    fn serialize_key<T>(&mut self, key: &T) -> Result<()>
693    where
694        T: ?Sized + Serialize,
695    {
696        key.serialize(&mut **self)
697    }
698
699    #[inline]
700    fn serialize_value<T>(&mut self, value: &T) -> Result<()>
701    where
702        T: ?Sized + Serialize,
703    {
704        value.serialize(&mut **self)
705    }
706
707    #[inline]
708    fn end(self) -> Result<()> {
709        Ok(())
710    }
711}
712
713impl<F> ser::SerializeStruct for &mut Serializer<F>
714where
715    F: Flavor,
716{
717    type Ok = ();
718    type Error = Error;
719
720    #[inline]
721    fn serialize_field<T>(&mut self, _key: &'static str, value: &T) -> Result<()>
722    where
723        T: ?Sized + Serialize,
724    {
725        value.serialize(&mut **self)
726    }
727
728    #[inline]
729    fn end(self) -> Result<()> {
730        Ok(())
731    }
732}
733
734impl<F> ser::SerializeStructVariant for &mut Serializer<F>
735where
736    F: Flavor,
737{
738    type Ok = ();
739    type Error = Error;
740
741    #[inline]
742    fn serialize_field<T>(&mut self, _key: &'static str, value: &T) -> Result<()>
743    where
744        T: ?Sized + Serialize,
745    {
746        value.serialize(&mut **self)
747    }
748
749    #[inline]
750    fn end(self) -> Result<()> {
751        Ok(())
752    }
753}
754
755fn zig_zag_i16(n: i16) -> u16 {
756    ((n << 1) ^ (n >> 15)) as u16
757}
758
759fn zig_zag_i32(n: i32) -> u32 {
760    ((n << 1) ^ (n >> 31)) as u32
761}
762
763fn zig_zag_i64(n: i64) -> u64 {
764    ((n << 1) ^ (n >> 63)) as u64
765}
766
767fn zig_zag_i128(n: i128) -> u128 {
768    ((n << 1) ^ (n >> 127)) as u128
769}
postcard/ser/serializer.rs

postcard/ser/
serializer.rs
