miniserde/ser/
mod.rs

1//! Serialization traits.
2//!
3//! Serialization in miniserde works by traversing an input object and
4//! decomposing it iteratively into a stream of fragments.
5//!
6//! ## Serializing a primitive
7//!
8//! ```rust
9//! use miniserde::ser::{Fragment, Serialize};
10//!
11//! // The data structure that we want to serialize as a primitive.
12//! struct MyBoolean(bool);
13//!
14//! impl Serialize for MyBoolean {
15//!     fn begin(&self) -> Fragment {
16//!         Fragment::Bool(self.0)
17//!     }
18//! }
19//! ```
20//!
21//! ## Serializing a sequence
22//!
23//! ```rust
24//! use miniserde::ser::{Fragment, Seq, Serialize};
25//!
26//! // Some custom sequence type that we want to serialize.
27//! struct MyVec<T>(Vec<T>);
28//!
29//! impl<T> Serialize for MyVec<T>
30//! where
31//!     T: Serialize,
32//! {
33//!     fn begin(&self) -> Fragment {
34//!         Fragment::Seq(Box::new(SliceStream { iter: self.0.iter() }))
35//!     }
36//! }
37//!
38//! struct SliceStream<'a, T: 'a> {
39//!     iter: std::slice::Iter<'a, T>,
40//! }
41//!
42//! impl<'a, T> Seq for SliceStream<'a, T>
43//! where
44//!     T: Serialize,
45//! {
46//!     fn next(&mut self) -> Option<&dyn Serialize> {
47//!         let element = self.iter.next()?;
48//!         Some(element)
49//!     }
50//! }
51//! ```
52//!
53//! ## Serializing a map or struct
54//!
55//! This code demonstrates what is generated for structs by
56//! `#[derive(Serialize)]`.
57//!
58//! ```rust
59//! use miniserde::ser::{Fragment, Map, Serialize};
60//! use std::borrow::Cow;
61//!
62//! // The struct that we would like to serialize.
63//! struct Demo {
64//!     code: u32,
65//!     message: String,
66//! }
67//!
68//! impl Serialize for Demo {
69//!     fn begin(&self) -> Fragment {
70//!         Fragment::Map(Box::new(DemoStream {
71//!             data: self,
72//!             state: 0,
73//!         }))
74//!     }
75//! }
76//!
77//! struct DemoStream<'a> {
78//!     data: &'a Demo,
79//!     state: usize,
80//! }
81//!
82//! impl<'a> Map for DemoStream<'a> {
83//!     fn next(&mut self) -> Option<(Cow<str>, &dyn Serialize)> {
84//!         let state = self.state;
85//!         self.state += 1;
86//!         match state {
87//!             0 => Some((Cow::Borrowed("code"), &self.data.code)),
88//!             1 => Some((Cow::Borrowed("message"), &self.data.message)),
89//!             _ => None,
90//!         }
91//!     }
92//! }
93//! ```
94
95mod impls;
96
97use alloc::borrow::Cow;
98use alloc::boxed::Box;
99
100/// One unit of output produced during serialization.
101///
102/// [Refer to the module documentation for examples.][crate::ser]
103pub enum Fragment<'a> {
104    Null,
105    Bool(bool),
106    Str(Cow<'a, str>),
107    U64(u64),
108    I64(i64),
109    F64(f64),
110    Seq(Box<dyn Seq + 'a>),
111    Map(Box<dyn Map + 'a>),
112}
113
114/// Trait for data structures that can be serialized to a JSON string.
115///
116/// [Refer to the module documentation for examples.][crate::ser]
117pub trait Serialize {
118    fn begin(&self) -> Fragment;
119}
120
121/// Trait that can iterate elements of a sequence.
122///
123/// [Refer to the module documentation for examples.][crate::ser]
124pub trait Seq {
125    fn next(&mut self) -> Option<&dyn Serialize>;
126}
127
128/// Trait that can iterate key-value entries of a map or struct.
129///
130/// [Refer to the module documentation for examples.][crate::ser]
131pub trait Map {
132    fn next(&mut self) -> Option<(Cow<str>, &dyn Serialize)>;
133}
miniserde/ser/mod.rs

miniserde/ser/
mod.rs
