Serde rustdoc
This commit is contained in:
parent
24f849da2d
commit
2c1dd60575
@ -26,3 +26,6 @@ unstable-testing = ["clippy", "unstable", "std"]
|
||||
|
||||
[dependencies]
|
||||
clippy = { version = "^0.*", optional = true }
|
||||
|
||||
[dev-dependencies]
|
||||
serde_derive = "0.9.0-rc3"
|
||||
|
@ -1,4 +1,20 @@
|
||||
//! Helper module to enable serializing bytes more efficiently
|
||||
//! Wrapper types to enable optimized handling of `&[u8]` and `Vec<u8>`.
|
||||
//!
|
||||
//! Without specialization, Rust forces us to treat `&[u8]` just like any other
|
||||
//! slice and `Vec<u8>` just like any other vector. In reality this particular
|
||||
//! slice and vector can often be serialized and deserialized in a more
|
||||
//! efficient, compact representation in many formats.
|
||||
//!
|
||||
//! When working with such a format, you can opt into specialized handling of
|
||||
//! `&[u8]` by wrapping it in `bytes::Bytes` and `Vec<u8>` by wrapping it in
|
||||
//! `bytes::ByteBuf`.
|
||||
//!
|
||||
//! Rust support for specialization is being tracked in
|
||||
//! [rust-lang/rust#31844][specialization]. Once it lands in the stable compiler
|
||||
//! we will be deprecating these wrapper types in favor of optimizing `&[u8]`
|
||||
//! and `Vec<u8>` out of the box.
|
||||
//!
|
||||
//! [specialization]: https://github.com/rust-lang/rust/issues/31844
|
||||
|
||||
use core::{ops, fmt, char, iter, slice};
|
||||
use core::fmt::Write;
|
||||
@ -6,14 +22,36 @@ use core::fmt::Write;
|
||||
use ser;
|
||||
|
||||
#[cfg(any(feature = "std", feature = "collections"))]
|
||||
pub use self::bytebuf::{ByteBuf, ByteBufVisitor};
|
||||
pub use self::bytebuf::ByteBuf;
|
||||
|
||||
#[cfg(any(feature = "std", feature = "collections"))]
|
||||
#[doc(hidden)] // does anybody need this?
|
||||
pub use self::bytebuf::ByteBufVisitor;
|
||||
|
||||
#[cfg(feature = "collections")]
|
||||
use collections::Vec;
|
||||
|
||||
///////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
/// `Bytes` wraps a `&[u8]` in order to serialize into a byte array.
|
||||
/// Wraps a `&[u8]` in order to serialize in an efficient way. Does not support
|
||||
/// deserialization.
|
||||
///
|
||||
/// ```rust
|
||||
/// # #[macro_use] extern crate serde_derive;
|
||||
/// # extern crate serde;
|
||||
/// # use std::net::IpAddr;
|
||||
/// #
|
||||
/// use serde::bytes::Bytes;
|
||||
///
|
||||
/// # #[allow(dead_code)]
|
||||
/// #[derive(Serialize)]
|
||||
/// struct Packet<'a> {
|
||||
/// destination: IpAddr,
|
||||
/// payload: Bytes<'a>,
|
||||
/// }
|
||||
/// #
|
||||
/// # fn main() {}
|
||||
/// ```
|
||||
#[derive(Clone, Copy, Eq, Hash, PartialEq, PartialOrd, Ord)]
|
||||
pub struct Bytes<'a> {
|
||||
bytes: &'a [u8],
|
||||
@ -86,7 +124,25 @@ mod bytebuf {
|
||||
#[cfg(feature = "collections")]
|
||||
use collections::{String, Vec};
|
||||
|
||||
/// `ByteBuf` wraps a `Vec<u8>` and serializes as a byte array.
|
||||
/// Wraps a `Vec<u8>` in order to serialize and deserialize in an efficient
|
||||
/// way.
|
||||
///
|
||||
/// ```rust
|
||||
/// # #[macro_use] extern crate serde_derive;
|
||||
/// # extern crate serde;
|
||||
/// # use std::net::IpAddr;
|
||||
/// #
|
||||
/// use serde::bytes::ByteBuf;
|
||||
///
|
||||
/// # #[allow(dead_code)]
|
||||
/// #[derive(Serialize, Deserialize)]
|
||||
/// struct Packet {
|
||||
/// destination: IpAddr,
|
||||
/// payload: ByteBuf,
|
||||
/// }
|
||||
/// #
|
||||
/// # fn main() {}
|
||||
/// ```
|
||||
#[derive(Clone, Default, Eq, Hash, PartialEq, PartialOrd, Ord)]
|
||||
pub struct ByteBuf {
|
||||
bytes: Vec<u8>,
|
||||
|
File diff suppressed because it is too large
Load Diff
@ -975,16 +975,16 @@ mod private {
|
||||
}
|
||||
|
||||
fn visit_tuple<V>(self,
|
||||
_len: usize,
|
||||
_visitor: V) -> Result<V::Value, Self::Error>
|
||||
_len: usize,
|
||||
_visitor: V) -> Result<V::Value, Self::Error>
|
||||
where V: de::Visitor
|
||||
{
|
||||
Err(de::Error::invalid_type(Unexpected::UnitVariant, &"tuple variant"))
|
||||
}
|
||||
|
||||
fn visit_struct<V>(self,
|
||||
_fields: &'static [&'static str],
|
||||
_visitor: V) -> Result<V::Value, Self::Error>
|
||||
_fields: &'static [&'static str],
|
||||
_visitor: V) -> Result<V::Value, Self::Error>
|
||||
where V: de::Visitor
|
||||
{
|
||||
Err(de::Error::invalid_type(Unexpected::UnitVariant, &"struct variant"))
|
||||
|
@ -1,13 +1,63 @@
|
||||
//! Serde Serialization Framework
|
||||
//! # Serde
|
||||
//!
|
||||
//! Serde is a powerful framework that enables serialization libraries to generically serialize
|
||||
//! Rust data structures without the overhead of runtime type information. In many situations, the
|
||||
//! handshake protocol between serializers and serializees can be completely optimized away,
|
||||
//! leaving serde to perform roughly the same speed as a hand written serializer for a specific
|
||||
//! type.
|
||||
//! Serde is a framework for ***ser***ializing and ***de***serializing Rust data
|
||||
//! structures efficiently and generically.
|
||||
//!
|
||||
//! For a detailed tutorial on the different ways to use serde please check out the
|
||||
//! [github repository](https://github.com/serde-rs/serde)
|
||||
//! The Serde ecosystem consists of data structures that know how to serialize
|
||||
//! and deserialize themselves along with data formats that know how to
|
||||
//! serialize and deserialize other things. Serde provides the layer by which
|
||||
//! these two groups interact with each other, allowing any supported data
|
||||
//! structure to be serialized and deserialized using any supported data format.
|
||||
//!
|
||||
//! See the Serde website https://serde.rs/ for additional documentation and
|
||||
//! usage examples.
|
||||
//!
|
||||
//! ### Design
|
||||
//!
|
||||
//! Where many other languages rely on runtime reflection for serializing data,
|
||||
//! Serde is instead built on Rust's powerful trait system. A data structure
|
||||
//! that knows how to serialize and deserialize itself is one that implements
|
||||
//! Serde's `Serialize` and `Deserialize` traits (or uses Serde's code
|
||||
//! generation to automatically derive implementations at compile time). This
|
||||
//! avoids any overhead of reflection or runtime type information. In fact in
|
||||
//! many situations the interaction between data structure and data format can
|
||||
//! be completely optimized away by the Rust compiler, leaving Serde
|
||||
//! serialization to perform roughly the same speed as a handwritten serializer
|
||||
//! for the specific selection of data structure and data format.
|
||||
//!
|
||||
//! ### Data formats
|
||||
//!
|
||||
//! The following is a partial list of data formats that have been implemented
|
||||
//! for Serde by the community.
|
||||
//!
|
||||
//! - [JSON](https://github.com/serde-rs/json), the ubiquitous JavaScript Object
|
||||
//! Notation used by many HTTP APIs.
|
||||
//! - [Bincode](https://github.com/TyOverby/bincode), a compact binary format
|
||||
//! used for IPC within the Servo rendering engine.
|
||||
//! - [CBOR](https://github.com/pyfisch/cbor), a Concise Binary Object
|
||||
//! Representation designed for small message size without the need for
|
||||
//! version negotiation.
|
||||
//! - [YAML](https://github.com/dtolnay/serde-yaml), a popular human-friendly
|
||||
//! configuration language that ain't markup language.
|
||||
//! - [MessagePack](https://github.com/3Hren/msgpack-rust), an efficient binary
|
||||
//! format that resembles a compact JSON.
|
||||
//! - [TOML](https://github.com/alexcrichton/toml-rs), a minimal configuration
|
||||
//! format used by [Cargo](http://doc.crates.io/manifest.html).
|
||||
//! - [Pickle](https://github.com/birkenfeld/serde-pickle), a format common in
|
||||
//! the Python world.
|
||||
//! - [Hjson](https://github.com/laktak/hjson-rust), a variant of JSON designed
|
||||
//! to be readable and writable by humans.
|
||||
//! - [BSON](https://github.com/zonyitoo/bson-rs), the data storage and network
|
||||
//! transfer format used by MongoDB.
|
||||
//! - [URL](https://github.com/nox/serde_urlencoded), the x-www-form-urlencoded
|
||||
//! format.
|
||||
//! - [XML](https://github.com/serde-rs/xml), the flexible machine-friendly W3C
|
||||
//! standard. *(deserialization only)*
|
||||
//! - [Envy](https://github.com/softprops/envy), a way to deserialize
|
||||
//! environment variables into Rust structs. *(deserialization only)*
|
||||
//! - [Redis](https://github.com/OneSignal/serde-redis), deserialize values from
|
||||
//! Redis when using [redis-rs](https://crates.io/crates/redis).
|
||||
//! *(deserialization only)*
|
||||
|
||||
#![doc(html_root_url="https://docs.serde.rs")]
|
||||
#![cfg_attr(not(feature = "std"), no_std)]
|
||||
@ -45,6 +95,7 @@ mod macros;
|
||||
pub mod bytes;
|
||||
pub mod de;
|
||||
#[cfg(feature = "std")]
|
||||
#[doc(hidden)]
|
||||
pub mod iter;
|
||||
pub mod ser;
|
||||
#[cfg_attr(feature = "std", doc(hidden))]
|
||||
|
@ -124,28 +124,70 @@ macro_rules! forward_to_deserialize_helper {
|
||||
};
|
||||
}
|
||||
|
||||
/// Helper to forward `Deserializer` methods to `Deserializer::deserialize`.
|
||||
/// Every given method ignores all arguments and forwards to `deserialize`.
|
||||
/// Note that `deserialize_enum` simply returns an `Error::invalid_type`; a
|
||||
/// better approach is tracked in [serde-rs/serde#521][1].
|
||||
// Super explicit first paragraph because this shows up at the top level and
|
||||
// trips up people who are just looking for basic Serialize / Deserialize
|
||||
// documentation.
|
||||
//
|
||||
/// Helper macro when implementing the `Deserializer` part of a new data format
|
||||
/// for Serde.
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// Some `Deserializer` implementations for self-describing formats do not care
|
||||
/// what hint the `Visitor` gives them, they just want to blindly call the
|
||||
/// `Visitor` method corresponding to the data they can tell is in the input.
|
||||
/// This requires repetitive implementations of all the `Deserializer` trait
|
||||
/// methods.
|
||||
///
|
||||
/// ```rust
|
||||
/// # #[macro_use] extern crate serde;
|
||||
/// # use serde::de::{value, Deserializer, Visitor};
|
||||
/// # pub struct MyDeserializer;
|
||||
/// # impl Deserializer for MyDeserializer {
|
||||
/// # type Error = value::Error;
|
||||
/// # fn deserialize<V>(self, _: V) -> Result<V::Value, Self::Error>
|
||||
/// # where V: Visitor
|
||||
/// # { unimplemented!() }
|
||||
/// #
|
||||
/// #[inline]
|
||||
/// fn deserialize_bool<V>(self, visitor: V) -> Result<V::Value, Self::Error>
|
||||
/// where V: Visitor
|
||||
/// {
|
||||
/// self.deserialize(visitor)
|
||||
/// }
|
||||
/// # forward_to_deserialize! {
|
||||
/// # usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 char str string
|
||||
/// # unit option seq seq_fixed_size bytes byte_buf map unit_struct
|
||||
/// # newtype_struct tuple_struct struct struct_field tuple enum ignored_any
|
||||
/// # }
|
||||
/// # }
|
||||
/// # fn main() {}
|
||||
/// ```
|
||||
///
|
||||
/// The `forward_to_deserialize!` macro implements these simple forwarding
|
||||
/// methods so that they forward directly to `Deserializer::deserialize`. You
|
||||
/// can choose which methods to forward.
|
||||
///
|
||||
/// ```rust
|
||||
/// # #[macro_use] extern crate serde;
|
||||
/// # use serde::de::{value, Deserializer, Visitor};
|
||||
/// # pub struct MyDeserializer;
|
||||
/// impl Deserializer for MyDeserializer {
|
||||
/// # type Error = value::Error;
|
||||
/// fn deserialize<V>(self, visitor: V) -> Result<V::Value, Self::Error>
|
||||
/// where V: Visitor
|
||||
/// {
|
||||
/// /* ... */
|
||||
/// # let _ = visitor;
|
||||
/// # unimplemented!()
|
||||
/// }
|
||||
///
|
||||
/// forward_to_deserialize! {
|
||||
/// bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 char str string
|
||||
/// unit option seq seq_fixed_size bytes map unit_struct newtype_struct
|
||||
/// tuple_struct struct struct_field tuple enum ignored_any
|
||||
/// bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 char str
|
||||
/// string unit option seq seq_fixed_size bytes byte_buf map unit_struct
|
||||
/// newtype_struct tuple_struct struct struct_field tuple enum ignored_any
|
||||
/// }
|
||||
/// }
|
||||
/// # fn main() {}
|
||||
/// ```
|
||||
///
|
||||
/// [1]: https://github.com/serde-rs/serde/issues/521
|
||||
#[macro_export]
|
||||
macro_rules! forward_to_deserialize {
|
||||
($($func:ident)*) => {
|
||||
|
@ -1,9 +1,3 @@
|
||||
//! Implementations for all of Rust's builtin types. Tuples implement the `Serialize` trait if they
|
||||
//! have at most 16 fields. Arrays implement the `Serialize` trait if their length is 32 or less.
|
||||
//! You can always forward array serialization to slice serialization, which works for any length.
|
||||
//! Long tuples are best replaced by tuple structs, for which you can use `derive(Serialize)`. In
|
||||
//! that case the number of fields is irrelevant.
|
||||
|
||||
#[cfg(feature = "std")]
|
||||
use std::borrow::Cow;
|
||||
#[cfg(all(feature = "collections", not(feature = "std")))]
|
||||
@ -772,7 +766,7 @@ impl Serialize for path::Path {
|
||||
{
|
||||
match self.to_str() {
|
||||
Some(s) => s.serialize(serializer),
|
||||
None => Err(Error::custom("Path contains invalid UTF-8 characters")),
|
||||
None => Err(Error::custom("path contains invalid UTF-8 characters")),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
@ -1,14 +1,97 @@
|
||||
//! Generic serialization framework.
|
||||
//! # For Developers who want to serialize objects
|
||||
//! Implement the `Serialize` trait for the type of objects you want to serialize. Call methods of
|
||||
//! the `serializer` object. For which methods to call and how to do so, look at the documentation
|
||||
//! of the `Serializer` trait.
|
||||
//! Generic data structure serialization framework.
|
||||
//!
|
||||
//! # For Serialization Format Developers
|
||||
//! Implement the `Serializer` trait for a structure that contains fields that enable it to write
|
||||
//! the serialization result to your target. When a method's argument is an object of type
|
||||
//! `Serialize`, you can either forward the serializer object (`self`) or create a new one,
|
||||
//! depending on the quirks of your format.
|
||||
//! The two most important traits in this module are `Serialize` and
|
||||
//! `Serializer`.
|
||||
//!
|
||||
//! - **A type that implements `Serialize` is a data structure** that can be
|
||||
//! serialized to any data format supported by Serde, and conversely
|
||||
//! - **A type that implements `Serializer` is a data format** that can
|
||||
//! serialize any data structure supported by Serde.
|
||||
//!
|
||||
//! # The Serialize trait
|
||||
//!
|
||||
//! Serde provides `Serialize` implementations for many Rust primitive and
|
||||
//! standard library types. The complete list is below. All of these can be
|
||||
//! serialized using Serde out of the box.
|
||||
//!
|
||||
//! Additionally, Serde provides a procedural macro called `serde_derive` to
|
||||
//! automatically generate `Serialize` implementations for structs and enums in
|
||||
//! your program. See the [codegen section of the manual][codegen] for how to
|
||||
//! use this.
|
||||
//!
|
||||
//! In rare cases it may be necessary to implement `Serialize` manually for some
|
||||
//! type in your program. See the [Implementing `Serialize`][impl-serialize]
|
||||
//! section of the manual for more about this.
|
||||
//!
|
||||
//! Third-party crates may provide `Serialize` implementations for types that
|
||||
//! they expose. For example the `linked-hash-map` crate provides a
|
||||
//! `LinkedHashMap<K, V>` type that is serializable by Serde because the crate
|
||||
//! provides an implementation of `Serialize` for it.
|
||||
//!
|
||||
//! # The Serializer trait
|
||||
//!
|
||||
//! `Serializer` implementations are provided by third-party crates, for example
|
||||
//! [`serde_json`][serde_json], [`serde_yaml`][serde_yaml] and
|
||||
//! [`bincode`][bincode].
|
||||
//!
|
||||
//! A partial list of well-maintained formats is given on the [Serde
|
||||
//! website][data-formats].
|
||||
//!
|
||||
//! # Implementations of Serialize provided by Serde
|
||||
//!
|
||||
//! - **Primitive types**:
|
||||
//! - bool
|
||||
//! - isize, i8, i16, i32, i64
|
||||
//! - usize, u8, u16, u32, u64
|
||||
//! - f32, f64
|
||||
//! - char
|
||||
//! - str
|
||||
//! - &T and &mut T
|
||||
//! - **Compound types**:
|
||||
//! - [T]
|
||||
//! - [T; 0] through [T; 32]
|
||||
//! - tuples up to size 16
|
||||
//! - **Common standard library types**:
|
||||
//! - String
|
||||
//! - Option\<T\>
|
||||
//! - Result\<T, E\>
|
||||
//! - PhantomData\<T\>
|
||||
//! - **Wrapper types**:
|
||||
//! - Box\<T\>
|
||||
//! - Rc\<T\>
|
||||
//! - Arc\<T\>
|
||||
//! - Cow\<'a, T\>
|
||||
//! - **Collection types**:
|
||||
//! - BTreeMap\<K, V\>
|
||||
//! - BTreeSet\<T\>
|
||||
//! - BinaryHeap\<T\>
|
||||
//! - HashMap\<K, V, H\>
|
||||
//! - HashSet\<T, H\>
|
||||
//! - LinkedList\<T\>
|
||||
//! - VecDeque\<T\>
|
||||
//! - Vec\<T\>
|
||||
//! - EnumSet\<T\> (unstable)
|
||||
//! - Range\<T\> (unstable)
|
||||
//! - RangeInclusive\<T\> (unstable)
|
||||
//! - **Miscellaneous standard library types**:
|
||||
//! - Duration
|
||||
//! - Path
|
||||
//! - PathBuf
|
||||
//! - NonZero\<T\> (unstable)
|
||||
//! - **Net types**:
|
||||
//! - IpAddr
|
||||
//! - Ipv4Addr
|
||||
//! - Ipv6Addr
|
||||
//! - SocketAddr
|
||||
//! - SocketAddrV4
|
||||
//! - SocketAddrV6
|
||||
//!
|
||||
//! [codegen]: https://serde.rs/codegen.html
|
||||
//! [impl-serialize]: https://serde.rs/impl-serialize.html
|
||||
//! [serde_json]: https://github.com/serde-rs/json
|
||||
//! [serde_yaml]: https://github.com/dtolnay/serde-yaml
|
||||
//! [bincode]: https://github.com/TyOverby/bincode
|
||||
//! [data-formats]: https://serde.rs/#data-formats
|
||||
|
||||
#[cfg(feature = "std")]
|
||||
use std::error;
|
||||
@ -20,52 +103,146 @@ use core::cell::RefCell;
|
||||
|
||||
use core::fmt::Display;
|
||||
|
||||
pub mod impls;
|
||||
mod impls;
|
||||
|
||||
///////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
/// `Error` is a trait that allows a `Serialize` to generically create a
|
||||
/// `Serializer` error.
|
||||
/// Trait used by `Serialize` implementations to generically construct errors
|
||||
/// belonging to the `Serializer` against which they are currently running.
|
||||
pub trait Error: Sized + error::Error {
|
||||
/// Raised when there is a general error when serializing a type.
|
||||
/// Raised when a `Serialize` implementation encounters a general error
|
||||
/// while serializing a type.
|
||||
///
|
||||
/// The message should not be capitalized and should not end with a period.
|
||||
///
|
||||
/// For example, a filesystem `Path` may refuse to serialize itself if it
|
||||
/// contains invalid UTF-8 data.
|
||||
///
|
||||
/// ```rust
|
||||
/// # use serde::ser::{Serialize, Serializer, Error};
|
||||
/// # struct Path;
|
||||
/// # impl Path { fn to_str(&self) -> Option<&str> { unimplemented!() } }
|
||||
/// impl Serialize for Path {
|
||||
/// fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
|
||||
/// where S: Serializer
|
||||
/// {
|
||||
/// match self.to_str() {
|
||||
/// Some(s) => s.serialize(serializer),
|
||||
/// None => Err(Error::custom("path contains invalid UTF-8 characters")),
|
||||
/// }
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
fn custom<T: Display>(msg: T) -> Self;
|
||||
}
|
||||
|
||||
///////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
/// A trait that describes a type that can be serialized by a `Serializer`.
|
||||
/// An implementation of this trait is a **data structure** that can be
|
||||
/// serialized into any data format supported by Serde.
|
||||
///
|
||||
/// Serde provides `Serialize` implementations for many Rust primitive and
|
||||
/// standard library types. The complete list is [here][ser]. All of these can
|
||||
/// be serialized using Serde out of the box.
|
||||
///
|
||||
/// Additionally, Serde provides a procedural macro called `serde_derive` to
|
||||
/// automatically generate `Serialize` implementations for structs and enums in
|
||||
/// your program. See the [codegen section of the manual][codegen] for how to
|
||||
/// use this.
|
||||
///
|
||||
/// In rare cases it may be necessary to implement `Serialize` manually for some
|
||||
/// type in your program. See the [Implementing `Serialize`][impl-serialize]
|
||||
/// section of the manual for more about this.
|
||||
///
|
||||
/// Third-party crates may provide `Serialize` implementations for types that
|
||||
/// they expose. For example the `linked-hash-map` crate provides a
|
||||
/// `LinkedHashMap<K, V>` type that is serializable by Serde because the crate
|
||||
/// provides an implementation of `Serialize` for it.
|
||||
///
|
||||
/// [ser]: https://docs.serde.rs/serde/ser/index.html
|
||||
/// [codegen]: https://serde.rs/codegen.html
|
||||
/// [impl-serialize]: https://serde.rs/impl-serialize.html
|
||||
pub trait Serialize {
|
||||
/// Serializes this value into this serializer.
|
||||
/// Serialize this value into the given Serde serializer.
|
||||
///
|
||||
/// See the [Implementing `Serialize`][impl-serialize] section of the manual
|
||||
/// for more information about how to implement this method.
|
||||
///
|
||||
/// [impl-serialize]: https://serde.rs/impl-serialize.html
|
||||
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
|
||||
where S: Serializer;
|
||||
}
|
||||
|
||||
///////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
/// A trait that describes a type that can serialize a stream of values into the underlying format.
|
||||
/// An implementation of this trait is a **data format** that can serialize any
|
||||
/// data structure supported by Serde.
|
||||
///
|
||||
/// # For `Serialize` Developers
|
||||
/// Non-aggregate types like integers and strings can be serialized directly by calling the
|
||||
/// appropriate function. For Aggregate types there's an initial `serialize_T` method that yields
|
||||
/// a State object that you should not interact with. For each part of the aggregate there's a
|
||||
/// `serialize_T_elt` method that allows you to pass values or key/value pairs. The types of the
|
||||
/// values or the keys may change between calls, but the serialization format may not necessarily
|
||||
/// accept it. The `serialize_T_elt` method also takes a mutable reference to the state object.
|
||||
/// Make sure that you always use the same state object and only the state object that was returned
|
||||
/// by the `serialize_T` method. Finally, when your object is done, call the `serialize_T_end`
|
||||
/// method and pass the state object by value
|
||||
/// The role of this trait is to define the serialization half of the Serde data
|
||||
/// model, which is a way to categorize every Rust data structure into one of 30
|
||||
/// possible types. Each method of the `Serializer` trait corresponds to one of
|
||||
/// the types of the data model.
|
||||
///
|
||||
/// # For Serialization Format Developers
|
||||
/// If your format has different situations where it accepts different types, create a
|
||||
/// `Serializer` for each situation. You can create the sub-`Serializer` in one of the aggregate
|
||||
/// `serialize_T` methods and return it as a state object. Remember to also set the corresponding
|
||||
/// associated type `TState`. In the `serialize_T_elt` methods you will be given a mutable
|
||||
/// reference to that state. You do not need to do any additional checks for the correctness of the
|
||||
/// state object, as it is expected that the user will not modify it. Due to the generic nature
|
||||
/// of the `Serialize` impls, modifying the object is impossible on stable Rust.
|
||||
/// Implementations of `Serialize` map themselves into this data model by
|
||||
/// invoking exactly one of the `Serializer` methods.
|
||||
///
|
||||
/// The types that make up the Serde data model are:
|
||||
///
|
||||
/// - 15 primitive types:
|
||||
/// - bool
|
||||
/// - isize, i8, i16, i32, i64
|
||||
/// - usize, u8, u16, u32, u64
|
||||
/// - f32, f64
|
||||
/// - char
|
||||
/// - string
|
||||
/// - byte array - [u8]
|
||||
/// - option
|
||||
/// - either none or some value
|
||||
/// - unit
|
||||
/// - unit is the type of () in Rust
|
||||
/// - unit_struct
|
||||
/// - for example `struct Unit` or `PhantomData<T>`
|
||||
/// - unit_variant
|
||||
/// - the `E::A` and `E::B` in `enum E { A, B }`
|
||||
/// - newtype_struct
|
||||
/// - for example `struct Millimeters(u8)`
|
||||
/// - newtype_variant
|
||||
/// - the `E::N` in `enum E { N(u8) }`
|
||||
/// - seq
|
||||
/// - a dynamically sized sequence of values, for example `Vec<T>` or
|
||||
/// `HashSet<T>`
|
||||
/// - seq_fixed_size
|
||||
/// - a statically sized sequence of values for which the size will be known
|
||||
/// at deserialization time without looking at the serialized data, for
|
||||
/// example `[u64; 10]`
|
||||
/// - tuple
|
||||
/// - for example `(u8,)` or `(String, u64, Vec<T>)`
|
||||
/// - tuple_struct
|
||||
/// - for example `struct Rgb(u8, u8, u8)`
|
||||
/// - tuple_variant
|
||||
/// - the `E::T` in `enum E { T(u8, u8) }`
|
||||
/// - map
|
||||
/// - for example `BTreeMap<K, V>`
|
||||
/// - struct
|
||||
/// - a key-value pairing in which the keys will be known at deserialization
|
||||
/// time without looking at the serialized data, for example `struct S { r:
|
||||
/// u8, g: u8, b: u8 }`
|
||||
/// - struct_variant
|
||||
/// - the `E::S` in `enum E { S { r: u8, g: u8, b: u8 } }`
|
||||
///
|
||||
/// Many Serde serializers produce text or binary data as output, for example
|
||||
/// JSON or Bincode. This is not a requirement of the `Serializer` trait, and
|
||||
/// there are serializers that do not produce text or binary output. One example
|
||||
/// is the `serde_json::value::Serializer` (distinct from the main `serde_json`
|
||||
/// serializer) that produces a `serde_json::Value` data structure in memory as
|
||||
/// output.
|
||||
pub trait Serializer {
|
||||
/// Trickery to enforce correct use of the `Serialize` trait. Every
|
||||
/// `Serializer` should set `Ok = ()`.
|
||||
/// The output type produced by this `Serializer` during successful
|
||||
/// serialization. Most serializers that produce text or binary output
|
||||
/// should set `Ok = ()` and serialize into an `io::Write` or buffer
|
||||
/// contained within the `Serializer` instance. Serializers that build
|
||||
/// in-memory data structures may be simplified by using `Ok` to propagate
|
||||
/// the data structure around.
|
||||
type Ok;
|
||||
|
||||
/// The error type when some error occurs during serialization.
|
||||
@ -99,75 +276,99 @@ pub trait Serializer {
|
||||
/// content of the struct variant.
|
||||
type SerializeStructVariant: SerializeStructVariant<Ok=Self::Ok, Error=Self::Error>;
|
||||
|
||||
/// Serializes a `bool` value.
|
||||
/// Serialize a `bool` value.
|
||||
fn serialize_bool(self, v: bool) -> Result<Self::Ok, Self::Error>;
|
||||
|
||||
/// Serializes an `isize` value. If the format does not differentiate
|
||||
/// between `isize` and `i64`, a reasonable implementation would be to cast
|
||||
/// the value to `i64` and forward to `serialize_i64`.
|
||||
/// Serialize an `isize` value.
|
||||
///
|
||||
/// If the format does not differentiate between `isize` and `i64`, a
|
||||
/// reasonable implementation would be to cast the value to `i64` and
|
||||
/// forward to `serialize_i64`.
|
||||
fn serialize_isize(self, v: isize) -> Result<Self::Ok, Self::Error>;
|
||||
|
||||
/// Serializes an `i8` value. If the format does not differentiate between
|
||||
/// `i8` and `i64`, a reasonable implementation would be to cast the value
|
||||
/// to `i64` and forward to `serialize_i64`.
|
||||
/// Serialize an `i8` value.
|
||||
///
|
||||
/// If the format does not differentiate between `i8` and `i64`, a
|
||||
/// reasonable implementation would be to cast the value to `i64` and
|
||||
/// forward to `serialize_i64`.
|
||||
fn serialize_i8(self, v: i8) -> Result<Self::Ok, Self::Error>;
|
||||
|
||||
/// Serializes an `i16` value. If the format does not differentiate between
|
||||
/// `i16` and `i64`, a reasonable implementation would be to cast the value
|
||||
/// to `i64` and forward to `serialize_i64`.
|
||||
/// Serialize an `i16` value.
|
||||
///
|
||||
/// If the format does not differentiate between `i16` and `i64`, a
|
||||
/// reasonable implementation would be to cast the value to `i64` and
|
||||
/// forward to `serialize_i64`.
|
||||
fn serialize_i16(self, v: i16) -> Result<Self::Ok, Self::Error>;
|
||||
|
||||
/// Serializes an `i32` value. If the format does not differentiate between
|
||||
/// `i32` and `i64`, a reasonable implementation would be to cast the value
|
||||
/// to `i64` and forward to `serialize_i64`.
|
||||
/// Serialize an `i32` value.
|
||||
///
|
||||
/// If the format does not differentiate between `i32` and `i64`, a
|
||||
/// reasonable implementation would be to cast the value to `i64` and
|
||||
/// forward to `serialize_i64`.
|
||||
fn serialize_i32(self, v: i32) -> Result<Self::Ok, Self::Error>;
|
||||
|
||||
/// Serializes an `i64` value.
|
||||
/// Serialize an `i64` value.
|
||||
fn serialize_i64(self, v: i64) -> Result<Self::Ok, Self::Error>;
|
||||
|
||||
/// Serializes a `usize` value. If the format does not differentiate between
|
||||
/// `usize` and `u64`, a reasonable implementation would be to cast the
|
||||
/// value to `u64` and forward to `serialize_u64`.
|
||||
/// Serialize a `usize` value.
|
||||
///
|
||||
/// If the format does not differentiate between `usize` and `u64`, a
|
||||
/// reasonable implementation would be to cast the value to `u64` and
|
||||
/// forward to `serialize_u64`.
|
||||
fn serialize_usize(self, v: usize) -> Result<Self::Ok, Self::Error>;
|
||||
|
||||
/// Serializes a `u8` value. If the format does not differentiate between
|
||||
/// `u8` and `u64`, a reasonable implementation would be to cast the value
|
||||
/// to `u64` and forward to `serialize_u64`.
|
||||
/// Serialize a `u8` value.
|
||||
///
|
||||
/// If the format does not differentiate between `u8` and `u64`, a
|
||||
/// reasonable implementation would be to cast the value to `u64` and
|
||||
/// forward to `serialize_u64`.
|
||||
fn serialize_u8(self, v: u8) -> Result<Self::Ok, Self::Error>;
|
||||
|
||||
/// Serializes a `u16` value. If the format does not differentiate between
|
||||
/// `u16` and `u64`, a reasonable implementation would be to cast the value
|
||||
/// to `u64` and forward to `serialize_u64`.
|
||||
/// Serialize a `u16` value.
|
||||
///
|
||||
/// If the format does not differentiate between `u16` and `u64`, a
|
||||
/// reasonable implementation would be to cast the value to `u64` and
|
||||
/// forward to `serialize_u64`.
|
||||
fn serialize_u16(self, v: u16) -> Result<Self::Ok, Self::Error>;
|
||||
|
||||
/// Serializes a `u32` value. If the format does not differentiate between
|
||||
/// `u32` and `u64`, a reasonable implementation would be to cast the value
|
||||
/// to `u64` and forward to `serialize_u64`.
|
||||
/// Serialize a `u32` value.
|
||||
///
|
||||
/// If the format does not differentiate between `u32` and `u64`, a
|
||||
/// reasonable implementation would be to cast the value to `u64` and
|
||||
/// forward to `serialize_u64`.
|
||||
fn serialize_u32(self, v: u32) -> Result<Self::Ok, Self::Error>;
|
||||
|
||||
/// `Serializes a `u64` value.
|
||||
/// Serialize a `u64` value.
|
||||
fn serialize_u64(self, v: u64) -> Result<Self::Ok, Self::Error>;
|
||||
|
||||
/// Serializes an `f32` value. If the format does not differentiate between
|
||||
/// `f32` and `f64`, a reasonable implementation would be to cast the value
|
||||
/// to `f64` and forward to `serialize_f64`.
|
||||
/// Serialize an `f32` value.
|
||||
///
|
||||
/// If the format does not differentiate between `f32` and `f64`, a
|
||||
/// reasonable implementation would be to cast the value to `f64` and
|
||||
/// forward to `serialize_f64`.
|
||||
fn serialize_f32(self, v: f32) -> Result<Self::Ok, Self::Error>;
|
||||
|
||||
/// Serializes an `f64` value.
|
||||
/// Serialize an `f64` value.
|
||||
fn serialize_f64(self, v: f64) -> Result<Self::Ok, Self::Error>;
|
||||
|
||||
/// Serializes a character. If the format does not support characters,
|
||||
/// it is reasonable to serialize it as a single element `str` or a `u32`.
|
||||
/// Serialize a character.
|
||||
///
|
||||
/// If the format does not support characters, it is reasonable to serialize
|
||||
/// it as a single element `str` or a `u32`.
|
||||
fn serialize_char(self, v: char) -> Result<Self::Ok, Self::Error>;
|
||||
|
||||
/// Serializes a `&str`.
|
||||
/// Serialize a `&str`.
|
||||
fn serialize_str(self, value: &str) -> Result<Self::Ok, Self::Error>;
|
||||
|
||||
/// Serialize a chunk of raw byte data.
|
||||
///
|
||||
/// Enables serializers to serialize byte slices more compactly or more
|
||||
/// efficiently than other types of slices. If no efficient implementation
|
||||
/// is available, a reasonable implementation would be to forward to
|
||||
/// `serialize_seq`. If forwarded, the implementation looks usually just like this:
|
||||
/// ```rust
|
||||
/// `serialize_seq`. If forwarded, the implementation looks usually just
|
||||
/// like this:
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// let mut seq = self.serialize_seq(Some(value.len()))?;
|
||||
/// for b in value {
|
||||
/// seq.serialize_element(b)?;
|
||||
@ -176,19 +377,40 @@ pub trait Serializer {
|
||||
/// ```
|
||||
fn serialize_bytes(self, value: &[u8]) -> Result<Self::Ok, Self::Error>;
|
||||
|
||||
/// Serializes a `()` value. It's reasonable to just not serialize anything.
|
||||
/// Serialize a `None` value.
|
||||
fn serialize_none(self) -> Result<Self::Ok, Self::Error>;
|
||||
|
||||
/// Serialize a `Some(T)` value.
|
||||
fn serialize_some<T: ?Sized + Serialize>(
|
||||
self,
|
||||
value: &T,
|
||||
) -> Result<Self::Ok, Self::Error>;
|
||||
|
||||
/// Serialize a `()` value.
|
||||
fn serialize_unit(self) -> Result<Self::Ok, Self::Error>;
|
||||
|
||||
/// Serializes a unit struct value. A reasonable implementation would be to
|
||||
/// forward to `serialize_unit`.
|
||||
/// Serialize a unit struct like `struct Unit` or `PhantomData<T>`.
|
||||
///
|
||||
/// A reasonable implementation would be to forward to `serialize_unit`.
|
||||
fn serialize_unit_struct(
|
||||
self,
|
||||
name: &'static str,
|
||||
) -> Result<Self::Ok, Self::Error>;
|
||||
|
||||
/// Serializes a unit variant, otherwise known as a variant with no
|
||||
/// arguments. A reasonable implementation would be to forward to
|
||||
/// `serialize_unit`.
|
||||
/// Serialize a unit variant like `E::A` in `enum E { A, B }`.
|
||||
///
|
||||
/// The `name` is the name of the enum, the `variant_index` is the index of
|
||||
/// this variant within the enum, and the `variant` is the name of the
|
||||
/// variant.
|
||||
///
|
||||
/// A reasonable implementation would be to forward to `serialize_unit`.
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// match *self {
|
||||
/// E::A => serializer.serialize_unit_variant("E", 0, "A"),
|
||||
/// E::B => serializer.serialize_unit_variant("E", 1, "B"),
|
||||
/// }
|
||||
/// ```
|
||||
fn serialize_unit_variant(
|
||||
self,
|
||||
name: &'static str,
|
||||
@ -196,19 +418,32 @@ pub trait Serializer {
|
||||
variant: &'static str,
|
||||
) -> Result<Self::Ok, Self::Error>;
|
||||
|
||||
/// Allows a tuple struct with a single element, also known as a newtype
|
||||
/// struct, to be more efficiently serialized than a tuple struct with
|
||||
/// multiple items. A reasonable implementation would be to forward to
|
||||
/// `serialize_tuple_struct` or to just serialize the inner value without wrapping.
|
||||
/// Serialize a newtype struct like `struct Millimeters(u8)`.
|
||||
///
|
||||
/// Serializers are encouraged to treat newtype structs as insignificant
|
||||
/// wrappers around the data they contain. A reasonable implementation would
|
||||
/// be to forward to `value.serialize(self)`.
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// serializer.serialize_newtype_struct("Millimeters", &self.0)
|
||||
/// ```
|
||||
fn serialize_newtype_struct<T: ?Sized + Serialize>(
|
||||
self,
|
||||
name: &'static str,
|
||||
value: &T,
|
||||
) -> Result<Self::Ok, Self::Error>;
|
||||
|
||||
/// Allows a variant with a single item to be more efficiently serialized
|
||||
/// than a variant with multiple items. A reasonable implementation would be
|
||||
/// to forward to `serialize_tuple_variant`.
|
||||
/// Serialize a newtype variant like `E::N` in `enum E { N(u8) }`.
|
||||
///
|
||||
/// The `name` is the name of the enum, the `variant_index` is the index of
|
||||
/// this variant within the enum, and the `variant` is the name of the
|
||||
/// variant. The `value` is the data contained within this newtype variant.
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// match *self {
|
||||
/// E::N(ref n) => serializer.serialize_newtype_variant("E", 0, "N", n),
|
||||
/// }
|
||||
/// ```
|
||||
fn serialize_newtype_variant<T: ?Sized + Serialize>(
|
||||
self,
|
||||
name: &'static str,
|
||||
@ -217,53 +452,96 @@ pub trait Serializer {
|
||||
value: &T,
|
||||
) -> Result<Self::Ok, Self::Error>;
|
||||
|
||||
/// Serializes a `None` value.
|
||||
fn serialize_none(self) -> Result<Self::Ok, Self::Error>;
|
||||
|
||||
/// Serializes a `Some(...)` value.
|
||||
fn serialize_some<T: ?Sized + Serialize>(
|
||||
self,
|
||||
value: &T,
|
||||
) -> Result<Self::Ok, Self::Error>;
|
||||
|
||||
/// Begins to serialize a sequence. This call must be followed by zero or
|
||||
/// more calls to `serialize_seq_elt`, then a call to `serialize_seq_end`.
|
||||
/// Begin to serialize a dynamically sized sequence. This call must be
|
||||
/// followed by zero or more calls to `serialize_element`, then a call to
|
||||
/// `end`.
|
||||
///
|
||||
/// The argument is the number of elements in the sequence, which may or may
|
||||
/// not be computable before the sequence is iterated. Some serializers only
|
||||
/// support sequences whose length is known up front.
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// let mut seq = serializer.serialize_seq(Some(self.len()))?;
|
||||
/// for element in self {
|
||||
/// seq.serialize_element(element)?;
|
||||
/// }
|
||||
/// seq.end()
|
||||
/// ```
|
||||
fn serialize_seq(
|
||||
self,
|
||||
len: Option<usize>,
|
||||
) -> Result<Self::SerializeSeq, Self::Error>;
|
||||
|
||||
/// Begins to serialize a sequence whose length will be known at
|
||||
/// deserialization time. This call must be followed by zero or more calls
|
||||
/// to `serialize_seq_elt`, then a call to `serialize_seq_end`. A reasonable
|
||||
/// implementation would be to forward to `serialize_seq`.
|
||||
/// Begin to serialize a statically sized sequence whose length will be
|
||||
/// known at deserialization time without looking at the serialized data.
|
||||
/// This call must be followed by zero or more calls to `serialize_element`,
|
||||
/// then a call to `end`.
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// let mut seq = serializer.serialize_seq_fixed_size(self.len())?;
|
||||
/// for element in self {
|
||||
/// seq.serialize_element(element)?;
|
||||
/// }
|
||||
/// seq.end()
|
||||
/// ```
|
||||
fn serialize_seq_fixed_size(
|
||||
self,
|
||||
size: usize,
|
||||
) -> Result<Self::SerializeSeq, Self::Error>;
|
||||
|
||||
/// Begins to serialize a tuple. This call must be followed by zero or more
|
||||
/// calls to `serialize_tuple_elt`, then a call to `serialize_tuple_end`. A
|
||||
/// reasonable implementation would be to forward to `serialize_seq`.
|
||||
/// Begin to serialize a tuple. This call must be followed by zero or more
|
||||
/// calls to `serialize_field`, then a call to `end`.
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// let mut tup = serializer.serialize_tuple(3)?;
|
||||
/// tup.serialize_field(&self.0)?;
|
||||
/// tup.serialize_field(&self.1)?;
|
||||
/// tup.serialize_field(&self.2)?;
|
||||
/// tup.end()
|
||||
/// ```
|
||||
fn serialize_tuple(
|
||||
self,
|
||||
len: usize,
|
||||
) -> Result<Self::SerializeTuple, Self::Error>;
|
||||
|
||||
/// Begins to serialize a tuple struct. This call must be followed by zero
|
||||
/// or more calls to `serialize_tuple_struct_elt`, then a call to
|
||||
/// `serialize_tuple_struct_end`. A reasonable implementation would be to
|
||||
/// forward to `serialize_tuple`.
|
||||
/// Begin to serialize a tuple struct like `struct Rgb(u8, u8, u8)`. This
|
||||
/// call must be followed by zero or more calls to `serialize_field`, then a
|
||||
/// call to `end`.
|
||||
///
|
||||
/// The `name` is the name of the tuple struct and the `len` is the number
|
||||
/// of data fields that will be serialized.
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// let mut ts = serializer.serialize_tuple_struct("Rgb", 3)?;
|
||||
/// ts.serialize_field(&self.0)?;
|
||||
/// ts.serialize_field(&self.1)?;
|
||||
/// ts.serialize_field(&self.2)?;
|
||||
/// ts.end()
|
||||
/// ```
|
||||
fn serialize_tuple_struct(
|
||||
self,
|
||||
name: &'static str,
|
||||
len: usize,
|
||||
) -> Result<Self::SerializeTupleStruct, Self::Error>;
|
||||
|
||||
/// Begins to serialize a tuple variant. This call must be followed by zero
|
||||
/// or more calls to `serialize_tuple_variant_elt`, then a call to
|
||||
/// `serialize_tuple_variant_end`. A reasonable implementation would be to
|
||||
/// forward to `serialize_tuple_struct`.
|
||||
/// Begin to serialize a tuple variant like `E::T` in `enum E { T(u8, u8)
|
||||
/// }`. This call must be followed by zero or more calls to
|
||||
/// `serialize_field`, then a call to `end`.
|
||||
///
|
||||
/// The `name` is the name of the enum, the `variant_index` is the index of
|
||||
/// this variant within the enum, the `variant` is the name of the variant,
|
||||
/// and the `len` is the number of data fields that will be serialized.
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// match *self {
|
||||
/// E::T(ref a, ref b) => {
|
||||
/// let mut tv = serializer.serialize_tuple_variant("E", 0, "T", 2)?;
|
||||
/// tv.serialize_field(a)?;
|
||||
/// tv.serialize_field(b)?;
|
||||
/// tv.end()
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
fn serialize_tuple_variant(
|
||||
self,
|
||||
name: &'static str,
|
||||
@ -272,25 +550,65 @@ pub trait Serializer {
|
||||
len: usize,
|
||||
) -> Result<Self::SerializeTupleVariant, Self::Error>;
|
||||
|
||||
/// Begins to serialize a map. This call must be followed by zero or more
|
||||
/// calls to `serialize_map_key` and `serialize_map_value`, then a call to
|
||||
/// `serialize_map_end`.
|
||||
/// Begin to serialize a map. This call must be followed by zero or more
|
||||
/// calls to `serialize_key` and `serialize_value`, then a call to `end`.
|
||||
///
|
||||
/// The argument is the number of elements in the map, which may or may not
|
||||
/// be computable before the map is iterated. Some serializers only support
|
||||
/// maps whose length is known up front.
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// let mut map = serializer.serialize_map(Some(self.len()))?;
|
||||
/// for (k, v) in self {
|
||||
/// map.serialize_key(k)?;
|
||||
/// map.serialize_value(v)?;
|
||||
/// }
|
||||
/// map.end()
|
||||
/// ```
|
||||
fn serialize_map(
|
||||
self,
|
||||
len: Option<usize>,
|
||||
) -> Result<Self::SerializeMap, Self::Error>;
|
||||
|
||||
/// Begins to serialize a struct. This call must be followed by zero or more
|
||||
/// calls to `serialize_struct_elt`, then a call to `serialize_struct_end`.
|
||||
/// Begin to serialize a struct like `struct Rgb { r: u8, g: u8, b: u8 }`.
|
||||
/// This call must be followed by zero or more calls to `serialize_field`,
|
||||
/// then a call to `end`.
|
||||
///
|
||||
/// The `name` is the name of the struct and the `len` is the number of
|
||||
/// data fields that will be serialized.
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// let mut struc = serializer.serialize_struct("Rgb", 3)?;
|
||||
/// struc.serialize_field("r", &self.r)?;
|
||||
/// struc.serialize_field("g", &self.g)?;
|
||||
/// struc.serialize_field("b", &self.b)?;
|
||||
/// struc.end()
|
||||
/// ```
|
||||
fn serialize_struct(
|
||||
self,
|
||||
name: &'static str,
|
||||
len: usize,
|
||||
) -> Result<Self::SerializeStruct, Self::Error>;
|
||||
|
||||
/// Begins to serialize a struct variant. This call must be followed by zero
|
||||
/// or more calls to `serialize_struct_variant_elt`, then a call to
|
||||
/// `serialize_struct_variant_end`.
|
||||
/// Begin to serialize a struct variant like `E::S` in `enum E { S { r: u8,
|
||||
/// g: u8, b: u8 } }`. This call must be followed by zero or more calls to
|
||||
/// `serialize_field`, then a call to `end`.
|
||||
///
|
||||
/// The `name` is the name of the enum, the `variant_index` is the index of
|
||||
/// this variant within the enum, the `variant` is the name of the variant,
|
||||
/// and the `len` is the number of data fields that will be serialized.
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// match *self {
|
||||
/// E::S { ref r, ref g, ref b } => {
|
||||
/// let mut sv = serializer.serialize_struct_variant("E", 0, "S", 3)?;
|
||||
/// sv.serialize_field("r", r)?;
|
||||
/// sv.serialize_field("g", g)?;
|
||||
/// sv.serialize_field("b", b)?;
|
||||
/// sv.end()
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
fn serialize_struct_variant(
|
||||
self,
|
||||
name: &'static str,
|
||||
@ -302,76 +620,115 @@ pub trait Serializer {
|
||||
|
||||
/// Returned from `Serializer::serialize_seq` and
|
||||
/// `Serializer::serialize_seq_fixed_size`.
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// let mut seq = serializer.serialize_seq(Some(self.len()))?;
|
||||
/// for element in self {
|
||||
/// seq.serialize_element(element)?;
|
||||
/// }
|
||||
/// seq.end()
|
||||
/// ```
|
||||
pub trait SerializeSeq {
|
||||
/// Trickery to enforce correct use of the `Serialize` trait. Every
|
||||
/// `SerializeSeq` should set `Ok = ()`.
|
||||
/// Must match the `Ok` type of our `Serializer`.
|
||||
type Ok;
|
||||
|
||||
/// The error type when some error occurs during serialization.
|
||||
/// Must match the `Error` type of our `Serializer`.
|
||||
type Error: Error;
|
||||
|
||||
/// Serializes a sequence element.
|
||||
/// Serialize a sequence element.
|
||||
fn serialize_element<T: ?Sized + Serialize>(&mut self, value: &T) -> Result<(), Self::Error>;
|
||||
|
||||
/// Finishes serializing a sequence.
|
||||
/// Finish serializing a sequence.
|
||||
fn end(self) -> Result<Self::Ok, Self::Error>;
|
||||
}
|
||||
|
||||
/// Returned from `Serializer::serialize_tuple`.
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// let mut tup = serializer.serialize_tuple(3)?;
|
||||
/// tup.serialize_field(&self.0)?;
|
||||
/// tup.serialize_field(&self.1)?;
|
||||
/// tup.serialize_field(&self.2)?;
|
||||
/// tup.end()
|
||||
/// ```
|
||||
pub trait SerializeTuple {
|
||||
/// Trickery to enforce correct use of the `Serialize` trait. Every
|
||||
/// `SerializeTuple` should set `Ok = ()`.
|
||||
/// Must match the `Ok` type of our `Serializer`.
|
||||
type Ok;
|
||||
|
||||
/// The error type when some error occurs during serialization.
|
||||
/// Must match the `Error` type of our `Serializer`.
|
||||
type Error: Error;
|
||||
|
||||
/// Serializes a tuple element.
|
||||
/// Serialize a tuple element.
|
||||
fn serialize_element<T: ?Sized + Serialize>(&mut self, value: &T) -> Result<(), Self::Error>;
|
||||
|
||||
/// Finishes serializing a tuple.
|
||||
/// Finish serializing a tuple.
|
||||
fn end(self) -> Result<Self::Ok, Self::Error>;
|
||||
}
|
||||
|
||||
/// Returned from `Serializer::serialize_tuple_struct`.
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// let mut ts = serializer.serialize_tuple_struct("Rgb", 3)?;
|
||||
/// ts.serialize_field(&self.0)?;
|
||||
/// ts.serialize_field(&self.1)?;
|
||||
/// ts.serialize_field(&self.2)?;
|
||||
/// ts.end()
|
||||
/// ```
|
||||
pub trait SerializeTupleStruct {
|
||||
/// Trickery to enforce correct use of the `Serialize` trait. Every
|
||||
/// `SerializeTupleStruct` should set `Ok = ()`.
|
||||
/// Must match the `Ok` type of our `Serializer`.
|
||||
type Ok;
|
||||
|
||||
/// The error type when some error occurs during serialization.
|
||||
/// Must match the `Error` type of our `Serializer`.
|
||||
type Error: Error;
|
||||
|
||||
/// Serializes a tuple struct element.
|
||||
/// Serialize a tuple struct field.
|
||||
fn serialize_field<T: ?Sized + Serialize>(&mut self, value: &T) -> Result<(), Self::Error>;
|
||||
|
||||
/// Finishes serializing a tuple struct.
|
||||
/// Finish serializing a tuple struct.
|
||||
fn end(self) -> Result<Self::Ok, Self::Error>;
|
||||
}
|
||||
|
||||
/// Returned from `Serializer::serialize_tuple_variant`.
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// match *self {
|
||||
/// E::T(ref a, ref b) => {
|
||||
/// let mut tv = serializer.serialize_tuple_variant("E", 0, "T", 2)?;
|
||||
/// tv.serialize_field(a)?;
|
||||
/// tv.serialize_field(b)?;
|
||||
/// tv.end()
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
pub trait SerializeTupleVariant {
|
||||
/// Trickery to enforce correct use of the `Serialize` trait. Every
|
||||
/// `SerializeTupleVariant` should set `Ok = ()`.
|
||||
/// Must match the `Ok` type of our `Serializer`.
|
||||
type Ok;
|
||||
|
||||
/// The error type when some error occurs during serialization.
|
||||
/// Must match the `Error` type of our `Serializer`.
|
||||
type Error: Error;
|
||||
|
||||
/// Serializes a tuple variant element.
|
||||
/// Serialize a tuple variant field.
|
||||
fn serialize_field<T: ?Sized + Serialize>(&mut self, value: &T) -> Result<(), Self::Error>;
|
||||
|
||||
/// Finishes serializing a tuple variant.
|
||||
/// Finish serializing a tuple variant.
|
||||
fn end(self) -> Result<Self::Ok, Self::Error>;
|
||||
}
|
||||
|
||||
/// Returned from `Serializer::serialize_map`.
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// let mut map = serializer.serialize_map(Some(self.len()))?;
|
||||
/// for (k, v) in self {
|
||||
/// map.serialize_key(k)?;
|
||||
/// map.serialize_value(v)?;
|
||||
/// }
|
||||
/// map.end()
|
||||
/// ```
|
||||
pub trait SerializeMap {
|
||||
/// Trickery to enforce correct use of the `Serialize` trait. Every
|
||||
/// `SerializeMap` should set `Ok = ()`.
|
||||
/// Must match the `Ok` type of our `Serializer`.
|
||||
type Ok;
|
||||
|
||||
/// The error type when some error occurs during serialization.
|
||||
/// Must match the `Error` type of our `Serializer`.
|
||||
type Error: Error;
|
||||
|
||||
/// Serialize a map key.
|
||||
@ -380,52 +737,71 @@ pub trait SerializeMap {
|
||||
/// Serialize a map value.
|
||||
fn serialize_value<T: ?Sized + Serialize>(&mut self, value: &T) -> Result<(), Self::Error>;
|
||||
|
||||
/// Finishes serializing a map.
|
||||
/// Finish serializing a map.
|
||||
fn end(self) -> Result<Self::Ok, Self::Error>;
|
||||
}
|
||||
|
||||
/// Returned from `Serializer::serialize_struct`.
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// let mut struc = serializer.serialize_struct("Rgb", 3)?;
|
||||
/// struc.serialize_field("r", &self.r)?;
|
||||
/// struc.serialize_field("g", &self.g)?;
|
||||
/// struc.serialize_field("b", &self.b)?;
|
||||
/// struc.end()
|
||||
/// ```
|
||||
pub trait SerializeStruct {
|
||||
/// Trickery to enforce correct use of the `Serialize` trait. Every
|
||||
/// `SerializeStruct` should set `Ok = ()`.
|
||||
/// Must match the `Ok` type of our `Serializer`.
|
||||
type Ok;
|
||||
|
||||
/// The error type when some error occurs during serialization.
|
||||
/// Must match the `Error` type of our `Serializer`.
|
||||
type Error: Error;
|
||||
|
||||
/// Serializes a struct field.
|
||||
/// Serialize a struct field.
|
||||
fn serialize_field<T: ?Sized + Serialize>(&mut self, key: &'static str, value: &T) -> Result<(), Self::Error>;
|
||||
|
||||
/// Finishes serializing a struct.
|
||||
/// Finish serializing a struct.
|
||||
fn end(self) -> Result<Self::Ok, Self::Error>;
|
||||
}
|
||||
|
||||
/// Returned from `Serializer::serialize_struct_variant`.
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// match *self {
|
||||
/// E::S { ref r, ref g, ref b } => {
|
||||
/// let mut sv = serializer.serialize_struct_variant("E", 0, "S", 3)?;
|
||||
/// sv.serialize_field("r", r)?;
|
||||
/// sv.serialize_field("g", g)?;
|
||||
/// sv.serialize_field("b", b)?;
|
||||
/// sv.end()
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
pub trait SerializeStructVariant {
|
||||
/// Trickery to enforce correct use of the `Serialize` trait. Every
|
||||
/// `SerializeStructVariant` should set `Ok = ()`.
|
||||
/// Must match the `Ok` type of our `Serializer`.
|
||||
type Ok;
|
||||
|
||||
/// The error type when some error occurs during serialization.
|
||||
/// Must match the `Error` type of our `Serializer`.
|
||||
type Error: Error;
|
||||
|
||||
/// Serialize a struct variant element.
|
||||
/// Serialize a struct variant field.
|
||||
fn serialize_field<T: ?Sized + Serialize>(&mut self, key: &'static str, value: &T) -> Result<(), Self::Error>;
|
||||
|
||||
/// Finishes serializing a struct variant.
|
||||
/// Finish serializing a struct variant.
|
||||
fn end(self) -> Result<Self::Ok, Self::Error>;
|
||||
}
|
||||
|
||||
/// A wrapper type for iterators that implements `Serialize` for iterators whose items implement
|
||||
/// `Serialize`. Don't use multiple times. Create new versions of this with the `iterator` function
|
||||
/// every time you want to serialize an iterator.
|
||||
/// A wrapper type for iterators that implements `Serialize` for iterators whose
|
||||
/// items implement `Serialize`. Don't use multiple times. Create new versions
|
||||
/// of this with the `serde::ser::iterator` function every time you want to
|
||||
/// serialize an iterator.
|
||||
#[cfg(feature = "unstable")]
|
||||
pub struct Iterator<I>(RefCell<Option<I>>)
|
||||
where <I as IntoIterator>::Item: Serialize,
|
||||
I: IntoIterator;
|
||||
|
||||
/// Creates a temporary type that can be passed to any function expecting a `Serialize` and will
|
||||
/// serialize the given iterator as a sequence
|
||||
/// Create a wrapper type that can be passed to any function expecting a
|
||||
/// `Serialize` and will serialize the given iterator as a sequence.
|
||||
#[cfg(feature = "unstable")]
|
||||
pub fn iterator<I>(iter: I) -> Iterator<I>
|
||||
where <I as IntoIterator>::Item: Serialize,
|
||||
|
@ -432,7 +432,7 @@ fn test_cannot_serialize_paths() {
|
||||
assert_ser_tokens_error(
|
||||
&Path::new(path),
|
||||
&[],
|
||||
Error::Message("Path contains invalid UTF-8 characters".to_owned()));
|
||||
Error::Message("path contains invalid UTF-8 characters".to_owned()));
|
||||
|
||||
let mut path_buf = PathBuf::new();
|
||||
path_buf.push(path);
|
||||
@ -440,7 +440,7 @@ fn test_cannot_serialize_paths() {
|
||||
assert_ser_tokens_error(
|
||||
&path_buf,
|
||||
&[],
|
||||
Error::Message("Path contains invalid UTF-8 characters".to_owned()));
|
||||
Error::Message("path contains invalid UTF-8 characters".to_owned()));
|
||||
}
|
||||
|
||||
#[test]
|
||||
|
Loading…
x
Reference in New Issue
Block a user