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
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>,
F: FnOnce(&mut Self) -> Result<(), Self::Error>,
Emit an enumeration value.
name
indicates the enumeration type name.f
is a function that will callemit_enum_variant
oremit_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>,
&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 namev_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 callemit_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>,
&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>,
&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 callemit_enum_struct_variant_field
for each data item. It may not be called iflen
is0
.
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>,
&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>,
&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 callsemit_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>,
&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>,
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 callsemit_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>,
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>,
&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 callsemit_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>,
&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>,
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>,
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>,
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 callemit_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>,
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>,
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 callemit_map_elt_key
andemit_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>,
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 mapf
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>,
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 mapf
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
impl<'a> Encoder for Encoder<'a> type Error = EncoderError;