orengine_utils/rw_serde/
serializer.rs

1//! Serializer backed by an [`std::io::Write`](Write) implementation.
2//!
3//! This module provides a Serde serializer that writes values directly to any
4//! type implementing [`std::io::Write`](Write). It uses the same format as
5//! [`bincode`](https://github.com/bincode-org/bincode) with little endian bytes and varints.
6//!
7//! Since serialization is performed directly on the output stream, no
8//! intermediate buffer is required.
9//!
10//! # Example
11//!
12//! ```no_run
13//! use std::fs::File;
14//! use serde::Serialize;
15//! use orengine_utils::rw_serde::RWSerializer;
16//!
17//! #[derive(Serialize)]
18//! struct Person {
19//!     id: u64,
20//!     name: String,
21//! }
22//!
23//! let file = File::create("person.bin")?;
24//! let mut serializer = RWSerializer::new(file);
25//!
26//! Person {
27//!     id: 1,
28//!     name: "Alice".into(),
29//! }
30//! .serialize(&mut serializer)?;
31//!
32//! serializer.flush()?;
33//! # Ok::<(), Box<dyn std::error::Error>>(())
34//! ```
35use crate::varint::WriteVarInt;
36use serde;
37use serde::Serialize;
38use std::fmt::{Debug, Display, Formatter};
39use std::io::Write;
40
41/// A streaming Serde serializer over any [`std::io::Write`](Write) destination.
42///
43/// Values are written sequentially using the crate's binary encoding.
44pub struct RWSerializer<Dst: Write> {
45    destination: Dst,
46}
47
48impl<Dst: Write> RWSerializer<Dst> {
49    /// Creates a new serializer from a writer.
50    pub fn new(destination: Dst) -> Self {
51        Self { destination }
52    }
53
54    /// Consumes the serializer and returns the wrapped writer.
55    pub fn into_inner(self) -> Dst {
56        self.destination
57    }
58
59    /// Returns a mutable reference to the underlying writer.
60    pub fn as_dst_mut(&mut self) -> &mut Dst {
61        &mut self.destination
62    }
63
64    /// Returns a shared reference to the underlying writer.
65    pub fn as_dst(&self) -> &Dst {
66        &self.destination
67    }
68
69    /// Flushes buffered data to the underlying writer.
70    ///
71    /// This forwards directly to [`std::io::Write::flush`](Write::flush).
72    pub fn flush(&mut self) -> Result<(), std::io::Error> {
73        self.destination.flush()
74    }
75}
76
77/// Errors that can occur while serializing values.
78///
79/// These errors represent either I/O failures or unsupported serialization
80/// patterns encountered while producing the crate's binary format.
81#[derive(Debug)]
82pub enum SerializeError {
83    IO(std::io::Error),
84    SequenceWithoutLen,
85    FieldSkipped,
86    Custom(String),
87}
88
89impl Display for SerializeError {
90    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
91        match self {
92            Self::IO(err) => write!(f, "failed to write: {err}"),
93            Self::FieldSkipped => {
94                write!(f, "`skip_field` should be unreachable for `Serializer`")
95            }
96            Self::SequenceWithoutLen => {
97                write!(f, "the collection without known length was provided")
98            }
99            Self::Custom(msg) => write!(f, "{msg}"),
100        }
101    }
102}
103
104impl std::error::Error for SerializeError {}
105
106impl serde::ser::Error for SerializeError {
107    fn custom<T>(msg: T) -> Self
108    where
109        T: Display,
110    {
111        Self::Custom(msg.to_string())
112    }
113}
114
115impl<'s, Dst: Write> serde::Serializer for &'s mut RWSerializer<Dst> {
116    type Ok = usize;
117    type Error = SerializeError;
118    type SerializeSeq = SerializerWithAcc<'s, Dst>;
119    type SerializeTuple = SerializerWithAcc<'s, Dst>;
120    type SerializeTupleStruct = SerializerWithAcc<'s, Dst>;
121    type SerializeTupleVariant = SerializerWithAcc<'s, Dst>;
122    type SerializeMap = SerializerWithAcc<'s, Dst>;
123    type SerializeStruct = SerializerWithAcc<'s, Dst>;
124    type SerializeStructVariant = SerializerWithAcc<'s, Dst>;
125
126    fn serialize_bool(self, v: bool) -> Result<Self::Ok, Self::Error> {
127        self.destination
128            .write_all(&[u8::from(v)])
129            .map_err(SerializeError::IO)?;
130
131        Ok(1)
132    }
133
134    fn serialize_i8(self, v: i8) -> Result<Self::Ok, Self::Error> {
135        self.destination.write_varint(v).map_err(SerializeError::IO)
136    }
137
138    fn serialize_i16(self, v: i16) -> Result<Self::Ok, Self::Error> {
139        self.destination.write_varint(v).map_err(SerializeError::IO)
140    }
141
142    fn serialize_i32(self, v: i32) -> Result<Self::Ok, Self::Error> {
143        self.destination.write_varint(v).map_err(SerializeError::IO)
144    }
145
146    fn serialize_i64(self, v: i64) -> Result<Self::Ok, Self::Error> {
147        self.destination.write_varint(v).map_err(SerializeError::IO)
148    }
149
150    fn serialize_i128(self, v: i128) -> Result<Self::Ok, Self::Error> {
151        self.destination.write_varint(v).map_err(SerializeError::IO)
152    }
153
154    fn serialize_u8(self, v: u8) -> Result<Self::Ok, Self::Error> {
155        self.destination.write_varint(v).map_err(SerializeError::IO)
156    }
157
158    fn serialize_u16(self, v: u16) -> Result<Self::Ok, Self::Error> {
159        self.destination.write_varint(v).map_err(SerializeError::IO)
160    }
161
162    fn serialize_u32(self, v: u32) -> Result<Self::Ok, Self::Error> {
163        self.destination.write_varint(v).map_err(SerializeError::IO)
164    }
165
166    fn serialize_u64(self, v: u64) -> Result<Self::Ok, Self::Error> {
167        self.destination.write_varint(v).map_err(SerializeError::IO)
168    }
169
170    fn serialize_u128(self, v: u128) -> Result<Self::Ok, Self::Error> {
171        self.destination.write_varint(v).map_err(SerializeError::IO)
172    }
173
174    fn serialize_f32(self, v: f32) -> Result<Self::Ok, Self::Error> {
175        self.destination
176            .write_all(&v.to_le_bytes())
177            .map_err(SerializeError::IO)?;
178
179        Ok(size_of::<f32>())
180    }
181
182    fn serialize_f64(self, v: f64) -> Result<Self::Ok, Self::Error> {
183        self.destination
184            .write_all(&v.to_le_bytes())
185            .map_err(SerializeError::IO)?;
186
187        Ok(size_of::<f64>())
188    }
189
190    fn serialize_char(self, v: char) -> Result<Self::Ok, Self::Error> {
191        self.destination
192            .write_all(&(v as u32).to_le_bytes())
193            .map_err(SerializeError::IO)?;
194
195        Ok(size_of::<char>())
196    }
197
198    fn serialize_str(self, v: &str) -> Result<Self::Ok, Self::Error> {
199        let written = self
200            .destination
201            .write_varint(v.len() as u64)
202            .map_err(SerializeError::IO)?;
203        self.destination
204            .write_all(v.as_bytes())
205            .map_err(SerializeError::IO)?;
206
207        Ok(written + v.len())
208    }
209
210    fn serialize_bytes(self, v: &[u8]) -> Result<Self::Ok, Self::Error> {
211        self.destination
212            .write_varint(v.len() as u64)
213            .map_err(SerializeError::IO)?;
214        self.destination.write_all(v).map_err(SerializeError::IO)?;
215
216        Ok(4 + v.len())
217    }
218
219    fn serialize_none(self) -> Result<Self::Ok, Self::Error> {
220        self.serialize_bool(false)
221    }
222
223    fn serialize_some<T>(self, value: &T) -> Result<Self::Ok, Self::Error>
224    where
225        T: ?Sized + Serialize,
226    {
227        self.serialize_bool(true)?;
228
229        Ok(1 + value.serialize(self)?)
230    }
231
232    #[inline]
233    fn serialize_unit(self) -> Result<Self::Ok, Self::Error> {
234        Ok(0)
235    }
236
237    #[inline]
238    fn serialize_unit_struct(self, _name: &'static str) -> Result<Self::Ok, Self::Error> {
239        Ok(0)
240    }
241
242    fn serialize_unit_variant(
243        self,
244        _name: &'static str,
245        variant_index: u32,
246        _variant: &'static str,
247    ) -> Result<Self::Ok, Self::Error> {
248        self.serialize_u32(variant_index)
249    }
250
251    fn serialize_newtype_struct<T>(
252        self,
253        _name: &'static str,
254        value: &T,
255    ) -> Result<Self::Ok, Self::Error>
256    where
257        T: ?Sized + Serialize,
258    {
259        value.serialize(self)
260    }
261
262    fn serialize_newtype_variant<T>(
263        self,
264        _name: &'static str,
265        variant_index: u32,
266        _variant: &'static str,
267        value: &T,
268    ) -> Result<Self::Ok, Self::Error>
269    where
270        T: ?Sized + Serialize,
271    {
272        Ok(self.serialize_u32(variant_index)? + value.serialize(self)?)
273    }
274
275    fn serialize_seq(self, len: Option<usize>) -> Result<Self::SerializeSeq, Self::Error> {
276        if let Some(len) = len {
277            Ok(SerializerWithAcc {
278                written: self
279                    .destination
280                    .write_varint(len as u64)
281                    .map_err(SerializeError::IO)?,
282                serializer: self,
283            })
284        } else {
285            Err(SerializeError::SequenceWithoutLen)
286        }
287    }
288
289    fn serialize_tuple(self, _len: usize) -> Result<Self::SerializeTuple, Self::Error> {
290        Ok(SerializerWithAcc {
291            written: 0,
292            serializer: self,
293        })
294    }
295
296    fn serialize_tuple_struct(
297        self,
298        _name: &'static str,
299        _len: usize,
300    ) -> Result<Self::SerializeTupleStruct, Self::Error> {
301        Ok(SerializerWithAcc {
302            written: 0,
303            serializer: self,
304        })
305    }
306
307    fn serialize_tuple_variant(
308        self,
309        _name: &'static str,
310        variant_index: u32,
311        _variant: &'static str,
312        _len: usize,
313    ) -> Result<Self::SerializeTupleVariant, Self::Error> {
314        let written = self
315            .destination
316            .write_varint(variant_index)
317            .map_err(SerializeError::IO)?;
318
319        Ok(SerializerWithAcc {
320            written,
321            serializer: self,
322        })
323    }
324
325    fn serialize_map(self, len: Option<usize>) -> Result<Self::SerializeMap, Self::Error> {
326        if let Some(len) = len {
327            Ok(SerializerWithAcc {
328                written: self
329                    .destination
330                    .write_varint(len as u64)
331                    .map_err(SerializeError::IO)?,
332                serializer: self,
333            })
334        } else {
335            Err(SerializeError::SequenceWithoutLen)
336        }
337    }
338
339    fn serialize_struct(
340        self,
341        _name: &'static str,
342        _len: usize,
343    ) -> Result<Self::SerializeStruct, Self::Error> {
344        Ok(SerializerWithAcc {
345            written: 0,
346            serializer: self,
347        })
348    }
349
350    fn serialize_struct_variant(
351        self,
352        _name: &'static str,
353        variant_index: u32,
354        _variant: &'static str,
355        _len: usize,
356    ) -> Result<Self::SerializeStructVariant, Self::Error> {
357        let written = self
358            .destination
359            .write_varint(variant_index)
360            .map_err(SerializeError::IO)?;
361
362        Ok(SerializerWithAcc {
363            written,
364            serializer: self,
365        })
366    }
367
368    fn is_human_readable(&self) -> bool {
369        false
370    }
371}
372
373pub struct SerializerWithAcc<'s, Dst: Write> {
374    serializer: &'s mut RWSerializer<Dst>,
375    written: usize,
376}
377
378impl<Dst: Write> serde::ser::SerializeSeq for SerializerWithAcc<'_, Dst> {
379    type Ok = usize;
380    type Error = SerializeError;
381
382    fn serialize_element<T>(&mut self, value: &T) -> Result<(), Self::Error>
383    where
384        T: ?Sized + Serialize,
385    {
386        self.written += value.serialize(&mut *self.serializer)?;
387
388        Ok(())
389    }
390
391    fn end(self) -> Result<Self::Ok, Self::Error> {
392        Ok(self.written)
393    }
394}
395
396impl<Dst: Write> serde::ser::SerializeTuple for SerializerWithAcc<'_, Dst> {
397    type Ok = usize;
398    type Error = SerializeError;
399
400    fn serialize_element<T>(&mut self, value: &T) -> Result<(), Self::Error>
401    where
402        T: ?Sized + Serialize,
403    {
404        self.written += value.serialize(&mut *self.serializer)?;
405
406        Ok(())
407    }
408
409    fn end(self) -> Result<Self::Ok, Self::Error> {
410        Ok(self.written)
411    }
412}
413
414impl<Dst: Write> serde::ser::SerializeTupleStruct for SerializerWithAcc<'_, Dst> {
415    type Ok = usize;
416    type Error = SerializeError;
417
418    fn serialize_field<T>(&mut self, value: &T) -> Result<(), Self::Error>
419    where
420        T: ?Sized + Serialize,
421    {
422        self.written += value.serialize(&mut *self.serializer)?;
423
424        Ok(())
425    }
426
427    fn end(self) -> Result<Self::Ok, Self::Error> {
428        Ok(self.written)
429    }
430}
431
432impl<Dst: Write> serde::ser::SerializeTupleVariant for SerializerWithAcc<'_, Dst> {
433    type Ok = usize;
434    type Error = SerializeError;
435
436    fn serialize_field<T>(&mut self, value: &T) -> Result<(), Self::Error>
437    where
438        T: ?Sized + Serialize,
439    {
440        self.written += value.serialize(&mut *self.serializer)?;
441
442        Ok(())
443    }
444
445    fn end(self) -> Result<Self::Ok, Self::Error> {
446        Ok(self.written)
447    }
448}
449
450impl<Dst: Write> serde::ser::SerializeMap for SerializerWithAcc<'_, Dst> {
451    type Ok = usize;
452    type Error = SerializeError;
453
454    fn serialize_key<T>(&mut self, key: &T) -> Result<(), Self::Error>
455    where
456        T: ?Sized + Serialize,
457    {
458        self.written += key.serialize(&mut *self.serializer)?;
459
460        Ok(())
461    }
462
463    fn serialize_value<T>(&mut self, value: &T) -> Result<(), Self::Error>
464    where
465        T: ?Sized + Serialize,
466    {
467        self.written += value.serialize(&mut *self.serializer)?;
468
469        Ok(())
470    }
471
472    fn end(self) -> Result<Self::Ok, Self::Error> {
473        Ok(self.written)
474    }
475}
476
477impl<Dst: Write> serde::ser::SerializeStruct for SerializerWithAcc<'_, Dst> {
478    type Ok = usize;
479    type Error = SerializeError;
480
481    fn serialize_field<T>(&mut self, _key: &'static str, value: &T) -> Result<(), Self::Error>
482    where
483        T: ?Sized + Serialize,
484    {
485        self.written += value.serialize(&mut *self.serializer)?;
486
487        Ok(())
488    }
489
490    fn skip_field(&mut self, _key: &'static str) -> Result<(), Self::Error> {
491        Err(SerializeError::FieldSkipped)
492    }
493
494    fn end(self) -> Result<Self::Ok, Self::Error> {
495        Ok(self.written)
496    }
497}
498
499impl<Dst: Write> serde::ser::SerializeStructVariant for SerializerWithAcc<'_, Dst> {
500    type Ok = usize;
501    type Error = SerializeError;
502
503    fn serialize_field<T>(&mut self, _key: &'static str, value: &T) -> Result<(), Self::Error>
504    where
505        T: ?Sized + Serialize,
506    {
507        self.written += value.serialize(&mut *self.serializer)?;
508
509        Ok(())
510    }
511
512    fn skip_field(&mut self, _key: &'static str) -> Result<(), Self::Error> {
513        Err(SerializeError::FieldSkipped)
514    }
515
516    fn end(self) -> Result<Self::Ok, Self::Error> {
517        Ok(self.written)
518    }
519}
orengine_utils/rw_serde/serializer.rs

orengine_utils/rw_serde/
serializer.rs
