Conventions

By convention a Serde data format crate provides the following in the root module or re-exported from the root module:

  • An Error type common to both serialization and deserialization.
  • A Result typedef which is equivalent to std::result::Result<T, Error>.
  • A Serializer type which implements serde::Serializer.
  • A Deserializer type which implements serde::Deserializer.
  • One or more to_abc functions depending on what types the format supports serializing to. For example to_string which returns a String, to_bytes which returns a Vec<u8>, or to_writer which writes into an io::Write.
  • One or more from_xyz functions depending on what types the format supports deserializing from. For example from_str which takes a &str, from_bytes which takes a &[u8], or from_reader which takes an io::Read.

In addition, formats that provide serialization-specific or deserialization-specific APIs beyond Serializer and Deserializer should expose those under top-level ser and de modules. For example serde_json provides a pluggable pretty-printer trait as serde_json::ser::Formatter.

A basic data format begins like this. The three modules are discussed in more detail on the following pages.

src/lib.rs

mod de;
mod error;
mod ser;

pub use de::{from_str, Deserializer};
pub use error::{Error, Result};
pub use ser::{to_string, Serializer};