Trait serde::Serializer [−] [src]

pub trait Serializer: Sized {
    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_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_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_none(self) -> Result<Self::Ok, Self::Error>;

    fn serialize_some<T: ?Sized + Serialize>(
        self, 
        value: &T
    ) -> 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_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>;

    fn collect_seq<I>(self, iter: I) -> Result<Self::Ok, Self::Error>
    where
        I: IntoIterator,
        <I as IntoIterator>::Item: Serialize,
    { ... }

    fn collect_map<K, V, I>(self, iter: I) -> Result<Self::Ok, Self::Error>
    where
        K: Serialize,
        V: Serialize,
        I: IntoIterator<Item = (K, V)>,
    { ... }

    fn collect_str<T: ?Sized>(self, value: &T) -> Result<Self::Ok, Self::Error>
    where
        T: Display,
    { ... }
}

A data format that can serialize any data structure supported by Serde.

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 28 possible types. Each method of the Serializer trait corresponds to one of the types of the data model.

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:

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.

Associated Types

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.

The error type when some error occurs during serialization.

Type returned from serialize_seq and serialize_seq_fixed_size for serializing the content of the sequence.

Type returned from serialize_tuple for serializing the content of the tuple.

Type returned from serialize_tuple_struct for serializing the content of the tuple struct.

Type returned from serialize_tuple_variant for serializing the content of the tuple variant.

Type returned from serialize_map for serializing the content of the map.

Type returned from serialize_struct for serializing the content of the struct.

Type returned from serialize_struct_variant for serializing the content of the struct variant.

Required Methods

Serialize a bool value.

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.

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.

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.

Serialize an i64 value.

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.

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.

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.

Serialize a u64 value.

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.

Serialize an f64 value.

Serialize 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 &str.

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:

ⓘThis example is not tested
let mut seq = self.serialize_seq(Some(value.len()))?;
for b in value {
    seq.serialize_element(b)?;
}
seq.end()

Serialize a None value.

Serialize a Some(T) value.

Serialize a () value.

Serialize a unit struct like struct Unit or PhantomData<T>.

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.

ⓘThis example is not tested
match *self {
    E::A => serializer.serialize_unit_variant("E", 0, "A"),
    E::B => serializer.serialize_unit_variant("E", 1, "B"),
}

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).

ⓘThis example is not tested
serializer.serialize_newtype_struct("Millimeters", &self.0)

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.

ⓘThis example is not tested
match *self {
    E::N(ref n) => serializer.serialize_newtype_variant("E", 0, "N", n),
}

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.

ⓘThis example is not tested
let mut seq = serializer.serialize_seq(Some(self.len()))?;
for element in self {
    seq.serialize_element(element)?;
}
seq.end()

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.

ⓘThis example is not tested
let mut seq = serializer.serialize_seq_fixed_size(self.len())?;
for element in self {
    seq.serialize_element(element)?;
}
seq.end()

Begin to serialize a tuple. This call must be followed by zero or more calls to serialize_element, then a call to end.

ⓘThis example is not tested
let mut tup = serializer.serialize_tuple(3)?;
tup.serialize_element(&self.0)?;
tup.serialize_element(&self.1)?;
tup.serialize_element(&self.2)?;
tup.end()

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.

ⓘThis example is not tested
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()

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.

ⓘThis example is not tested
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()
    }
}

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.

ⓘThis example is not tested
let mut map = serializer.serialize_map(Some(self.len()))?;
for (k, v) in self {
    map.serialize_entry(k, v)?;
}
map.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.

ⓘThis example is not tested
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()

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.

ⓘThis example is not tested
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()
    }
}

Provided Methods

Collect an iterator as a sequence.

The default implementation serializes each item yielded by the iterator using Self::SerializeSeq. Implementors should not need to override this method.

Collect an iterator as a map.

The default implementation serializes each pair yielded by the iterator using Self::SerializeMap. Implementors should not need to override this method.

Serialize a string produced by an implementation of Display.

The default implementation builds a heap-allocated String and delegates to serialize_str. Serializers are encouraged to provide a more efficient implementation if possible.

impl Serialize for DateTime {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
        where S: Serializer
    {
        serializer.collect_str(&format_args!("{:?}{:?}",
                                             self.naive_local(),
                                             self.offset()))
    }
}

Implementors