Trait rustc_serialize::Encoder [−] [src]

pub trait Encoder {
    type Error;
    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.

Associated Types

The error type for method results.

Required Methods

Emit a nil value.

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

Emit a usize value.

Emit a u64 value.

Emit a u32 value.

Emit a u16 value.

Emit a u8 value.

Emit a isize value.

Emit a i64 value.

Emit a i32 value.

Emit a i16 value.

Emit a i8 value.

Emit a bool value.

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

Emit a f64 value.

Emit a f32 value.

Emit a char value.

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

Emit a string value.

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.

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(())
                    })
                }
            }
        })
    }
}

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.

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(())
                    })
                }
            }
        })
    }
}

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.

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(())
        })
    }
}

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.

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.

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.

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(())
        })
    }
}

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.

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

Emit the None optional value.

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

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.

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.

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.

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(())
        })
    }
}

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.

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.

Implementors