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