Trait rustc_serialize::Encoder

pub trait Encoder {
    type Error;

    // Required methods
    fn emit_nil(&mut self) -> Result<(), Self::Error>;
    fn emit_usize(&mut self, v: usize) -> Result<(), Self::Error>;
    fn emit_u64(&mut self, v: u64) -> Result<(), Self::Error>;
    fn emit_u32(&mut self, v: u32) -> Result<(), Self::Error>;
    fn emit_u16(&mut self, v: u16) -> Result<(), Self::Error>;
    fn emit_u8(&mut self, v: u8) -> Result<(), Self::Error>;
    fn emit_isize(&mut self, v: isize) -> Result<(), Self::Error>;
    fn emit_i64(&mut self, v: i64) -> Result<(), Self::Error>;
    fn emit_i32(&mut self, v: i32) -> Result<(), Self::Error>;
    fn emit_i16(&mut self, v: i16) -> Result<(), Self::Error>;
    fn emit_i8(&mut self, v: i8) -> Result<(), Self::Error>;
    fn emit_bool(&mut self, v: bool) -> Result<(), Self::Error>;
    fn emit_f64(&mut self, v: f64) -> Result<(), Self::Error>;
    fn emit_f32(&mut self, v: f32) -> Result<(), Self::Error>;
    fn emit_char(&mut self, v: char) -> Result<(), Self::Error>;
    fn emit_str(&mut self, v: &str) -> Result<(), Self::Error>;
    fn emit_enum<F>(&mut self, name: &str, f: F) -> Result<(), Self::Error>
       where F: FnOnce(&mut Self) -> Result<(), Self::Error>;
    fn emit_enum_variant<F>(
        &mut self,
        v_name: &str,
        v_id: usize,
        len: usize,
        f: F
    ) -> Result<(), Self::Error>
       where F: FnOnce(&mut Self) -> Result<(), Self::Error>;
    fn emit_enum_variant_arg<F>(
        &mut self,
        a_idx: usize,
        f: F
    ) -> Result<(), Self::Error>
       where F: FnOnce(&mut Self) -> Result<(), Self::Error>;
    fn emit_enum_struct_variant<F>(
        &mut self,
        v_name: &str,
        v_id: usize,
        len: usize,
        f: F
    ) -> Result<(), Self::Error>
       where F: FnOnce(&mut Self) -> Result<(), Self::Error>;
    fn emit_enum_struct_variant_field<F>(
        &mut self,
        f_name: &str,
        f_idx: usize,
        f: F
    ) -> Result<(), Self::Error>
       where F: FnOnce(&mut Self) -> Result<(), Self::Error>;
    fn emit_struct<F>(
        &mut self,
        name: &str,
        len: usize,
        f: F
    ) -> Result<(), Self::Error>
       where F: FnOnce(&mut Self) -> Result<(), Self::Error>;
    fn emit_struct_field<F>(
        &mut self,
        f_name: &str,
        f_idx: usize,
        f: F
    ) -> Result<(), Self::Error>
       where F: FnOnce(&mut Self) -> Result<(), Self::Error>;
    fn emit_tuple<F>(&mut self, len: usize, f: F) -> Result<(), Self::Error>
       where F: FnOnce(&mut Self) -> Result<(), Self::Error>;
    fn emit_tuple_arg<F>(&mut self, idx: usize, f: F) -> Result<(), Self::Error>
       where F: FnOnce(&mut Self) -> Result<(), Self::Error>;
    fn emit_tuple_struct<F>(
        &mut self,
        name: &str,
        len: usize,
        f: F
    ) -> Result<(), Self::Error>
       where F: FnOnce(&mut Self) -> Result<(), Self::Error>;
    fn emit_tuple_struct_arg<F>(
        &mut self,
        f_idx: usize,
        f: F
    ) -> Result<(), Self::Error>
       where F: FnOnce(&mut Self) -> Result<(), Self::Error>;
    fn emit_option<F>(&mut self, f: F) -> Result<(), Self::Error>
       where F: FnOnce(&mut Self) -> Result<(), Self::Error>;
    fn emit_option_none(&mut self) -> Result<(), Self::Error>;
    fn emit_option_some<F>(&mut self, f: F) -> Result<(), Self::Error>
       where F: FnOnce(&mut Self) -> Result<(), Self::Error>;
    fn emit_seq<F>(&mut self, len: usize, f: F) -> Result<(), Self::Error>
       where F: FnOnce(&mut Self) -> Result<(), Self::Error>;
    fn emit_seq_elt<F>(&mut self, idx: usize, f: F) -> Result<(), Self::Error>
       where F: FnOnce(&mut Self) -> Result<(), Self::Error>;
    fn emit_map<F>(&mut self, len: usize, f: F) -> Result<(), Self::Error>
       where F: FnOnce(&mut Self) -> Result<(), Self::Error>;
    fn emit_map_elt_key<F>(
        &mut self,
        idx: usize,
        f: F
    ) -> Result<(), Self::Error>
       where F: FnOnce(&mut Self) -> Result<(), Self::Error>;
    fn emit_map_elt_val<F>(
        &mut self,
        idx: usize,
        f: F
    ) -> Result<(), Self::Error>
       where F: FnOnce(&mut Self) -> Result<(), Self::Error>;
}

Trait for writing out an encoding when serializing.

This trait provides methods to encode basic types and generic forms of collections. Implementations of Encodable use it to perform the actual encoding of a type.

It is unspecified what is done with the encoding - it could be stored in a variable, or written directly to a file, for example.

Encoders can expect to only have a single “root” method call made on this trait. Non-trivial types will call one of the collection-emitting methods, passing a function that may call other methods on the trait, but once the collection-emitting method has returned, encoding should be complete.

Required Associated Types

type Error

The error type for method results.

Required Methods

fn emit_nil(&mut self) -> Result<(), Self::Error>

Emit a nil value.

For example, this might be stored as the null keyword in JSON.

fn emit_usize(&mut self, v: usize) -> Result<(), Self::Error>

Emit a usize value.

fn emit_u64(&mut self, v: u64) -> Result<(), Self::Error>

Emit a u64 value.

fn emit_u32(&mut self, v: u32) -> Result<(), Self::Error>

Emit a u32 value.

fn emit_u16(&mut self, v: u16) -> Result<(), Self::Error>

Emit a u16 value.

fn emit_u8(&mut self, v: u8) -> Result<(), Self::Error>

Emit a u8 value.

fn emit_isize(&mut self, v: isize) -> Result<(), Self::Error>

Emit a isize value.

fn emit_i64(&mut self, v: i64) -> Result<(), Self::Error>

Emit a i64 value.

fn emit_i32(&mut self, v: i32) -> Result<(), Self::Error>

Emit a i32 value.

fn emit_i16(&mut self, v: i16) -> Result<(), Self::Error>

Emit a i16 value.

fn emit_i8(&mut self, v: i8) -> Result<(), Self::Error>

Emit a i8 value.

fn emit_bool(&mut self, v: bool) -> Result<(), Self::Error>

Emit a bool value.

For example, this might be stored as the true and false keywords in JSON.

fn emit_f64(&mut self, v: f64) -> Result<(), Self::Error>

Emit a f64 value.

fn emit_f32(&mut self, v: f32) -> Result<(), Self::Error>

Emit a f32 value.

fn emit_char(&mut self, v: char) -> Result<(), Self::Error>

Emit a char value.

Note that strings should be emitted using emit_str, not as a sequence of emit_char calls.

fn emit_str(&mut self, v: &str) -> Result<(), Self::Error>

Emit a string value.

fn emit_enum<F>(&mut self, name: &str, f: F) -> Result<(), Self::Error>where F: FnOnce(&mut Self) -> Result<(), Self::Error>,

Emit an enumeration value.

• name indicates the enumeration type name.
• f is a function that will call emit_enum_variant or emit_enum_struct_variant as appropriate to write the actual value.

fn emit_enum_variant<F>( &mut self, v_name: &str, v_id: usize, len: usize, f: F ) -> Result<(), Self::Error>where F: FnOnce(&mut Self) -> Result<(), Self::Error>,

Emit a enumeration variant value with no or unnamed data.

This should only be called from a function passed to emit_enum. Variants with named data should use emit_enum_struct_variant.

• v_name is the variant name
• v_id is the numeric identifier for the variant.
• len is the number of data items associated with the variant.
• f is a function that will call emit_enum_variant_arg for each data item. It may not be called if len is 0.

Examples

use rustc_serialize::Encodable;
use rustc_serialize::Encoder;

enum Message {
    Quit,
    ChangeColor(i32, i32, i32),
}

impl Encodable for Message {
    fn encode<S: Encoder>(&self, s: &mut S) -> Result<(), S::Error> {
        s.emit_enum("Message", |s| {
            match *self {
                Message::Quit => {
                    s.emit_enum_variant("Quit", 0, 0, |s| Ok(()))
                }
                Message::ChangeColor(r, g, b) => {
                    s.emit_enum_variant("ChangeColor", 1, 3, |s| {
                        try!(s.emit_enum_variant_arg(0, |s| {
                            s.emit_i32(r)
                        }));
                        try!(s.emit_enum_variant_arg(1, |s| {
                            s.emit_i32(g)
                        }));
                        try!(s.emit_enum_variant_arg(2, |s| {
                            s.emit_i32(b)
                        }));
                        Ok(())
                    })
                }
            }
        })
    }
}

fn emit_enum_variant_arg<F>( &mut self, a_idx: usize, f: F ) -> Result<(), Self::Error>where F: FnOnce(&mut Self) -> Result<(), Self::Error>,

Emit an unnamed data item for an enumeration variant.

This should only be called from a function passed to emit_enum_variant.

• a_idx is the (zero-based) index of the data item.
• f is a function that will call the appropriate emit method to encode the data object.

Note that variant data items must be emitted in order - starting with index 0 and finishing with index len-1.

fn emit_enum_struct_variant<F>( &mut self, v_name: &str, v_id: usize, len: usize, f: F ) -> Result<(), Self::Error>where F: FnOnce(&mut Self) -> Result<(), Self::Error>,

Emit a enumeration variant value with no or named data.

This should only be called from a function passed to emit_enum. Variants with unnamed data should use emit_enum_variant.

• v_name is the variant name.
• v_id is the numeric identifier for the variant.
• len is the number of data items associated with the variant.
• f is a function that will call emit_enum_struct_variant_field for each data item. It may not be called if len is 0.

Examples

use rustc_serialize::Encodable;
use rustc_serialize::Encoder;

enum Message {
    Quit,
    Move { x: i32, y: i32 },
}

impl Encodable for Message {
    fn encode<S: Encoder>(&self, s: &mut S) -> Result<(), S::Error> {
        s.emit_enum("Message", |s| {
            match *self {
                Message::Quit => {
                    s.emit_enum_struct_variant("Quit", 0, 0, |s| Ok(()))
                }
                Message::Move { x: x, y: y } => {
                    s.emit_enum_struct_variant("Move", 1, 2, |s| {
                        try!(s.emit_enum_struct_variant_field("x", 0, |s| {
                            s.emit_i32(x)
                        }));
                        try!(s.emit_enum_struct_variant_field("y", 1, |s| {
                            s.emit_i32(y)
                        }));
                        Ok(())
                    })
                }
            }
        })
    }
}

fn emit_enum_struct_variant_field<F>( &mut self, f_name: &str, f_idx: usize, f: F ) -> Result<(), Self::Error>where F: FnOnce(&mut Self) -> Result<(), Self::Error>,

Emit a named data item for an enumeration variant.

This should only be called from a function passed to emit_enum_struct_variant.

• f_name is the name of the data item field.
• f_idx is its (zero-based) index.
• f is a function that will call the appropriate emit method to encode the data object.

Note that fields must be emitted in order - starting with index 0 and finishing with index len-1.

fn emit_struct<F>( &mut self, name: &str, len: usize, f: F ) -> Result<(), Self::Error>where F: FnOnce(&mut Self) -> Result<(), Self::Error>,

Emit a struct value.

• name is the name of the struct.
• len is the number of members.
• f is a function that calls emit_struct_field for each member.

Examples

use rustc_serialize::Encodable;
use rustc_serialize::Encoder;

struct Point {
    x: i32,
    y: i32,
}

impl Encodable for Point {
    fn encode<S: Encoder>(&self, s: &mut S) -> Result<(), S::Error> {
        s.emit_struct("Point", 2, |s| {
            try!(s.emit_struct_field("x", 0, |s| {
                s.emit_i32(self.x)
            }));
            try!(s.emit_struct_field("y", 1, |s| {
                s.emit_i32(self.y)
            }));
            Ok(())
        })
    }
}

fn emit_struct_field<F>( &mut self, f_name: &str, f_idx: usize, f: F ) -> Result<(), Self::Error>where F: FnOnce(&mut Self) -> Result<(), Self::Error>,

Emit a field item for a struct.

This should only be called from a function passed to emit_struct.

• f_name is the name of the data item field.
• f_idx is its (zero-based) index.
• f is a function that will call the appropriate emit method to encode the data object.

Note that fields must be emitted in order - starting with index 0 and finishing with index len-1.

fn emit_tuple<F>(&mut self, len: usize, f: F) -> Result<(), Self::Error>where F: FnOnce(&mut Self) -> Result<(), Self::Error>,

Emit a tuple value.

• len is the number of items in the tuple.
• f is a function that calls emit_tuple_arg for each member.

Note that external Encodable implementations should not normally need to use this method directly; it is meant for the use of this module’s own implementation of Encodable for tuples.

fn emit_tuple_arg<F>(&mut self, idx: usize, f: F) -> Result<(), Self::Error>where F: FnOnce(&mut Self) -> Result<(), Self::Error>,

Emit a data item for a tuple.

This should only be called from a function passed to emit_tuple.

• idx is the (zero-based) index of the data item.
• f is a function that will call the appropriate emit method to encode the data object.

Note that tuple items must be emitted in order - starting with index 0 and finishing with index len-1.

fn emit_tuple_struct<F>( &mut self, name: &str, len: usize, f: F ) -> Result<(), Self::Error>where F: FnOnce(&mut Self) -> Result<(), Self::Error>,

Emit a tuple struct value.

• name is the name of the tuple struct.
• len is the number of items in the tuple struct.
• f is a function that calls emit_tuple_struct_arg for each member.

Examples

use rustc_serialize::Encodable;
use rustc_serialize::Encoder;

struct Pair(i32,i32);

impl Encodable for Pair {
    fn encode<S: Encoder>(&self, s: &mut S) -> Result<(), S::Error> {
        let Pair(first,second) = *self;
        s.emit_tuple_struct("Pair", 2, |s| {
            try!(s.emit_tuple_arg(0, |s| {
                s.emit_i32(first)
            }));
            try!(s.emit_tuple_arg(1, |s| {
                s.emit_i32(second)
            }));
            Ok(())
        })
    }
}

fn emit_tuple_struct_arg<F>( &mut self, f_idx: usize, f: F ) -> Result<(), Self::Error>where F: FnOnce(&mut Self) -> Result<(), Self::Error>,

Emit a data item for a tuple struct.

This should only be called from a function passed to emit_tuple_struct.

• f_idx is the (zero-based) index of the data item.
• f is a function that will call the appropriate emit method to encode the data object.

Note that tuple items must be emitted in order - starting with index 0 and finishing with index len-1.

fn emit_option<F>(&mut self, f: F) -> Result<(), Self::Error>where F: FnOnce(&mut Self) -> Result<(), Self::Error>,

Emit an optional value.

f is a function that will call either emit_option_none or emit_option_some as appropriate.

This method allows encoders to handle Option<T> values specially, rather than using the generic enum methods, because many encoding formats have a built-in “optional” concept.

Note that external Encodable implementations should not normally need to use this method directly; it is meant for the use of this module’s own implementation of Encodable for Option<T>.

fn emit_option_none(&mut self) -> Result<(), Self::Error>

Emit the None optional value.

This should only be called from a function passed to emit_option.

fn emit_option_some<F>(&mut self, f: F) -> Result<(), Self::Error>where F: FnOnce(&mut Self) -> Result<(), Self::Error>,

Emit the Some(x) optional value.

f is a function that will call the appropriate emit method to encode the data object.

This should only be called from a function passed to emit_option.

fn emit_seq<F>(&mut self, len: usize, f: F) -> Result<(), Self::Error>where F: FnOnce(&mut Self) -> Result<(), Self::Error>,

Emit a sequence of values.

This should be used for both array-like ordered sequences and set-like unordered ones.

• len is the number of values in the sequence.
• f is a function that will call emit_seq_elt for each value in the sequence.

fn emit_seq_elt<F>(&mut self, idx: usize, f: F) -> Result<(), Self::Error>where F: FnOnce(&mut Self) -> Result<(), Self::Error>,

Emit an element in a sequence.

This should only be called from a function passed to emit_seq.

• idx is the (zero-based) index of the value in the sequence.
• f is a function that will call the appropriate emit method to encode the data object.

Note that sequence elements must be emitted in order - starting with index 0 and finishing with index len-1.

fn emit_map<F>(&mut self, len: usize, f: F) -> Result<(), Self::Error>where F: FnOnce(&mut Self) -> Result<(), Self::Error>,

Emit an associative container (map).

• len is the number of entries in the map.
• f is a function that will call emit_map_elt_key and emit_map_elt_val for each entry in the map.

Examples

use rustc_serialize::Encodable;
use rustc_serialize::Encoder;

struct SimpleMap<K,V> {
    entries: Vec<(K,V)>,
}

impl<K:Encodable,V:Encodable> Encodable for SimpleMap<K,V> {
    fn encode<S: Encoder>(&self, s: &mut S) -> Result<(), S::Error> {
        s.emit_map(self.entries.len(), |s| {
            for (i, e) in self.entries.iter().enumerate() {
                let (ref k, ref v) = *e;
                try!(s.emit_map_elt_key(i, |s| k.encode(s)));
                try!(s.emit_map_elt_val(i, |s| v.encode(s)));
            }
            Ok(())
        })
    }
}

fn emit_map_elt_key<F>(&mut self, idx: usize, f: F) -> Result<(), Self::Error>where F: FnOnce(&mut Self) -> Result<(), Self::Error>,

Emit the key for an entry in a map.

This should only be called from a function passed to emit_map.

• idx is the (zero-based) index of the entry in the map
• f is a function that will call the appropriate emit method to encode the key.

Note that map entries must be emitted in order - starting with index 0 and finishing with index len-1 - and for each entry, the key should be emitted followed immediately by the value.

fn emit_map_elt_val<F>(&mut self, idx: usize, f: F) -> Result<(), Self::Error>where F: FnOnce(&mut Self) -> Result<(), Self::Error>,

Emit the value for an entry in a map.

This should only be called from a function passed to emit_map.

• idx is the (zero-based) index of the entry in the map
• f is a function that will call the appropriate emit method to encode the value.

Note that map entries must be emitted in order - starting with index 0 and finishing with index len-1 - and for each entry, the key should be emitted followed immediately by the value.

Object Safety

This trait is not object safe.

Implementors

impl<'a> Encoder for Encoder<'a>

type Error = EncoderError