Trait serde::ser::Serializer
[−]
[src]
pub trait Serializer { type Ok; type Error: Error; type SerializeSeq: SerializeSeq<Ok=Self::Ok, Error=Self::Error>; type SerializeTuple: SerializeTuple<Ok=Self::Ok, Error=Self::Error>; type SerializeTupleStruct: SerializeTupleStruct<Ok=Self::Ok, Error=Self::Error>; type SerializeTupleVariant: SerializeTupleVariant<Ok=Self::Ok, Error=Self::Error>; type SerializeMap: SerializeMap<Ok=Self::Ok, Error=Self::Error>; type SerializeStruct: SerializeStruct<Ok=Self::Ok, Error=Self::Error>; type SerializeStructVariant: SerializeStructVariant<Ok=Self::Ok, Error=Self::Error>; fn serialize_bool(self, v: bool) -> Result<Self::Ok, Self::Error>; fn serialize_isize(self, v: isize) -> Result<Self::Ok, Self::Error>; fn serialize_i8(self, v: i8) -> Result<Self::Ok, Self::Error>; fn serialize_i16(self, v: i16) -> Result<Self::Ok, Self::Error>; fn serialize_i32(self, v: i32) -> Result<Self::Ok, Self::Error>; fn serialize_i64(self, v: i64) -> Result<Self::Ok, Self::Error>; fn serialize_usize(self, v: usize) -> Result<Self::Ok, Self::Error>; fn serialize_u8(self, v: u8) -> Result<Self::Ok, Self::Error>; fn serialize_u16(self, v: u16) -> Result<Self::Ok, Self::Error>; fn serialize_u32(self, v: u32) -> Result<Self::Ok, Self::Error>; fn serialize_u64(self, v: u64) -> Result<Self::Ok, Self::Error>; fn serialize_f32(self, v: f32) -> Result<Self::Ok, Self::Error>; fn serialize_f64(self, v: f64) -> Result<Self::Ok, Self::Error>; fn serialize_char(self, v: char) -> Result<Self::Ok, Self::Error>; fn serialize_str(self, value: &str) -> Result<Self::Ok, Self::Error>; fn serialize_bytes(self, value: &[u8]) -> Result<Self::Ok, Self::Error>; fn serialize_unit(self) -> Result<Self::Ok, Self::Error>; fn serialize_unit_struct(self,
name: &'static str)
-> Result<Self::Ok, Self::Error>; fn serialize_unit_variant(self,
name: &'static str,
variant_index: usize,
variant: &'static str)
-> Result<Self::Ok, Self::Error>; fn serialize_newtype_struct<T: ?Sized + Serialize>(self,
name: &'static str,
value: &T)
-> Result<Self::Ok, Self::Error>; fn serialize_newtype_variant<T: ?Sized + Serialize>(self,
name: &'static str,
variant_index: usize,
variant: &'static str,
value: &T)
-> Result<Self::Ok, Self::Error>; fn serialize_none(self) -> Result<Self::Ok, Self::Error>; fn serialize_some<T: ?Sized + Serialize>(self,
value: &T)
-> Result<Self::Ok, Self::Error>; fn serialize_seq(self,
len: Option<usize>)
-> Result<Self::SerializeSeq, Self::Error>; fn serialize_seq_fixed_size(self,
size: usize)
-> Result<Self::SerializeSeq, Self::Error>; fn serialize_tuple(self,
len: usize)
-> Result<Self::SerializeTuple, Self::Error>; fn serialize_tuple_struct(self,
name: &'static str,
len: usize)
-> Result<Self::SerializeTupleStruct, Self::Error>; fn serialize_tuple_variant(self,
name: &'static str,
variant_index: usize,
variant: &'static str,
len: usize)
-> Result<Self::SerializeTupleVariant, Self::Error>; fn serialize_map(self,
len: Option<usize>)
-> Result<Self::SerializeMap, Self::Error>; fn serialize_struct(self,
name: &'static str,
len: usize)
-> Result<Self::SerializeStruct, Self::Error>; fn serialize_struct_variant(self,
name: &'static str,
variant_index: usize,
variant: &'static str,
len: usize)
-> Result<Self::SerializeStructVariant, Self::Error>; }
A trait that describes a type that can serialize a stream of values into the underlying format.
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
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.
Associated Types
type Ok
Trickery to enforce correct use of the Serialize
trait. Every
Serializer
should set Ok = ()
.
type Error: Error
The error type when some error occurs during serialization.
type SerializeSeq: SerializeSeq<Ok=Self::Ok, Error=Self::Error>
Type returned from serialize_seq
and serialize_seq_fixed_size
for
serializing the content of the sequence.
type SerializeTuple: SerializeTuple<Ok=Self::Ok, Error=Self::Error>
Type returned from serialize_tuple
for serializing the content of the
tuple.
type SerializeTupleStruct: SerializeTupleStruct<Ok=Self::Ok, Error=Self::Error>
Type returned from serialize_tuple_struct
for serializing the content
of the tuple struct.
type SerializeTupleVariant: SerializeTupleVariant<Ok=Self::Ok, Error=Self::Error>
Type returned from serialize_tuple_variant
for serializing the content
of the tuple variant.
type SerializeMap: SerializeMap<Ok=Self::Ok, Error=Self::Error>
Type returned from serialize_map
for serializing the content of the
map.
type SerializeStruct: SerializeStruct<Ok=Self::Ok, Error=Self::Error>
Type returned from serialize_struct
for serializing the content of the
struct.
type SerializeStructVariant: SerializeStructVariant<Ok=Self::Ok, Error=Self::Error>
Type returned from serialize_struct_variant
for serializing the
content of the struct variant.
Required Methods
fn serialize_bool(self, v: bool) -> Result<Self::Ok, Self::Error>
Serializes a bool
value.
fn serialize_isize(self, v: isize) -> 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
.
fn serialize_i8(self, v: i8) -> 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
.
fn serialize_i16(self, v: i16) -> 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
.
fn serialize_i32(self, v: i32) -> 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
.
fn serialize_i64(self, v: i64) -> Result<Self::Ok, Self::Error>
Serializes an i64
value.
fn serialize_usize(self, v: usize) -> 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
.
fn serialize_u8(self, v: u8) -> 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
.
fn serialize_u16(self, v: u16) -> 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
.
fn serialize_u32(self, v: u32) -> 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
.
fn serialize_u64(self, v: u64) -> Result<Self::Ok, Self::Error>
Serializes a
u64` value.
fn serialize_f32(self, v: f32) -> 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
.
fn serialize_f64(self, v: f64) -> Result<Self::Ok, Self::Error>
Serializes an f64
value.
fn serialize_char(self, v: char) -> 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
.
fn serialize_str(self, value: &str) -> Result<Self::Ok, Self::Error>
Serializes a &str
.
fn serialize_bytes(self, value: &[u8]) -> Result<Self::Ok, Self::Error>
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 let mut seq = self.serialize_seq(Some(value.len()))?; for b in value { seq.serialize_element(b)?; } seq.end()
fn serialize_unit(self) -> Result<Self::Ok, Self::Error>
Serializes a ()
value. It's reasonable to just not serialize anything.
fn serialize_unit_struct(self,
name: &'static str)
-> Result<Self::Ok, Self::Error>
name: &'static str)
-> Result<Self::Ok, Self::Error>
Serializes a unit struct value. A reasonable implementation would be to
forward to serialize_unit
.
fn serialize_unit_variant(self,
name: &'static str,
variant_index: usize,
variant: &'static str)
-> Result<Self::Ok, Self::Error>
name: &'static str,
variant_index: usize,
variant: &'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
.
fn serialize_newtype_struct<T: ?Sized + Serialize>(self,
name: &'static str,
value: &T)
-> Result<Self::Ok, Self::Error>
name: &'static str,
value: &T)
-> 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.
fn serialize_newtype_variant<T: ?Sized + Serialize>(self,
name: &'static str,
variant_index: usize,
variant: &'static str,
value: &T)
-> Result<Self::Ok, Self::Error>
name: &'static str,
variant_index: usize,
variant: &'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
.
fn serialize_none(self) -> Result<Self::Ok, Self::Error>
Serializes a None
value.
fn serialize_some<T: ?Sized + Serialize>(self,
value: &T)
-> Result<Self::Ok, Self::Error>
value: &T)
-> Result<Self::Ok, Self::Error>
Serializes a Some(...)
value.
fn serialize_seq(self,
len: Option<usize>)
-> Result<Self::SerializeSeq, Self::Error>
len: Option<usize>)
-> Result<Self::SerializeSeq, 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
.
fn serialize_seq_fixed_size(self,
size: usize)
-> Result<Self::SerializeSeq, Self::Error>
size: 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
.
fn serialize_tuple(self,
len: usize)
-> Result<Self::SerializeTuple, Self::Error>
len: usize)
-> Result<Self::SerializeTuple, 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
.
fn serialize_tuple_struct(self,
name: &'static str,
len: usize)
-> Result<Self::SerializeTupleStruct, Self::Error>
name: &'static str,
len: usize)
-> Result<Self::SerializeTupleStruct, 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
.
fn serialize_tuple_variant(self,
name: &'static str,
variant_index: usize,
variant: &'static str,
len: usize)
-> Result<Self::SerializeTupleVariant, Self::Error>
name: &'static str,
variant_index: usize,
variant: &'static str,
len: usize)
-> Result<Self::SerializeTupleVariant, 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
.
fn serialize_map(self,
len: Option<usize>)
-> Result<Self::SerializeMap, Self::Error>
len: Option<usize>)
-> Result<Self::SerializeMap, 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
.
fn serialize_struct(self,
name: &'static str,
len: usize)
-> Result<Self::SerializeStruct, Self::Error>
name: &'static str,
len: usize)
-> Result<Self::SerializeStruct, 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
.
fn serialize_struct_variant(self,
name: &'static str,
variant_index: usize,
variant: &'static str,
len: usize)
-> Result<Self::SerializeStructVariant, Self::Error>
name: &'static str,
variant_index: usize,
variant: &'static str,
len: usize)
-> Result<Self::SerializeStructVariant, 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
.