Trait rustc_serialize::Decoder [−][src]
pub trait Decoder { type Error; fn read_nil(&mut self) -> Result<(), Self::Error>; fn read_usize(&mut self) -> Result<usize, Self::Error>; fn read_u64(&mut self) -> Result<u64, Self::Error>; fn read_u32(&mut self) -> Result<u32, Self::Error>; fn read_u16(&mut self) -> Result<u16, Self::Error>; fn read_u8(&mut self) -> Result<u8, Self::Error>; fn read_isize(&mut self) -> Result<isize, Self::Error>; fn read_i64(&mut self) -> Result<i64, Self::Error>; fn read_i32(&mut self) -> Result<i32, Self::Error>; fn read_i16(&mut self) -> Result<i16, Self::Error>; fn read_i8(&mut self) -> Result<i8, Self::Error>; fn read_bool(&mut self) -> Result<bool, Self::Error>; fn read_f64(&mut self) -> Result<f64, Self::Error>; fn read_f32(&mut self) -> Result<f32, Self::Error>; fn read_char(&mut self) -> Result<char, Self::Error>; fn read_str(&mut self) -> Result<String, Self::Error>; fn read_enum<T, F>(&mut self, name: &str, f: F) -> Result<T, Self::Error>
where
F: FnOnce(&mut Self) -> Result<T, Self::Error>; fn read_enum_variant<T, F>(
&mut self,
names: &[&str],
f: F
) -> Result<T, Self::Error>
where
F: FnMut(&mut Self, usize) -> Result<T, Self::Error>; fn read_enum_variant_arg<T, F>(
&mut self,
a_idx: usize,
f: F
) -> Result<T, Self::Error>
where
F: FnOnce(&mut Self) -> Result<T, Self::Error>; fn read_enum_struct_variant<T, F>(
&mut self,
names: &[&str],
f: F
) -> Result<T, Self::Error>
where
F: FnMut(&mut Self, usize) -> Result<T, Self::Error>; fn read_enum_struct_variant_field<T, F>(
&mut self,
f_name: &str,
f_idx: usize,
f: F
) -> Result<T, Self::Error>
where
F: FnOnce(&mut Self) -> Result<T, Self::Error>; fn read_struct<T, F>(
&mut self,
s_name: &str,
len: usize,
f: F
) -> Result<T, Self::Error>
where
F: FnOnce(&mut Self) -> Result<T, Self::Error>; fn read_struct_field<T, F>(
&mut self,
f_name: &str,
f_idx: usize,
f: F
) -> Result<T, Self::Error>
where
F: FnOnce(&mut Self) -> Result<T, Self::Error>; fn read_tuple<T, F>(&mut self, len: usize, f: F) -> Result<T, Self::Error>
where
F: FnOnce(&mut Self) -> Result<T, Self::Error>; fn read_tuple_arg<T, F>(
&mut self,
a_idx: usize,
f: F
) -> Result<T, Self::Error>
where
F: FnOnce(&mut Self) -> Result<T, Self::Error>; fn read_tuple_struct<T, F>(
&mut self,
s_name: &str,
len: usize,
f: F
) -> Result<T, Self::Error>
where
F: FnOnce(&mut Self) -> Result<T, Self::Error>; fn read_tuple_struct_arg<T, F>(
&mut self,
a_idx: usize,
f: F
) -> Result<T, Self::Error>
where
F: FnOnce(&mut Self) -> Result<T, Self::Error>; fn read_option<T, F>(&mut self, f: F) -> Result<T, Self::Error>
where
F: FnMut(&mut Self, bool) -> Result<T, Self::Error>; fn read_seq<T, F>(&mut self, f: F) -> Result<T, Self::Error>
where
F: FnOnce(&mut Self, usize) -> Result<T, Self::Error>; fn read_seq_elt<T, F>(&mut self, idx: usize, f: F) -> Result<T, Self::Error>
where
F: FnOnce(&mut Self) -> Result<T, Self::Error>; fn read_map<T, F>(&mut self, f: F) -> Result<T, Self::Error>
where
F: FnOnce(&mut Self, usize) -> Result<T, Self::Error>; fn read_map_elt_key<T, F>(
&mut self,
idx: usize,
f: F
) -> Result<T, Self::Error>
where
F: FnOnce(&mut Self) -> Result<T, Self::Error>; fn read_map_elt_val<T, F>(
&mut self,
idx: usize,
f: F
) -> Result<T, Self::Error>
where
F: FnOnce(&mut Self) -> Result<T, Self::Error>; fn error(&mut self, err: &str) -> Self::Error; }
Trait for reading in an encoding for deserialization.
This trait provides methods to decode basic types and generic forms of
collections. Implementations of Decodable
use it to perform the actual
decoding of a type.
Note that, as is typical with deserialization, the design of this API assumes you know in advance the form of the data you are decoding (ie: what type is encoded).
Decoders can expect to only have a single "root" method call made on this trait. Non-trivial types will call one of the collection-reading methods, passing a function that may call other methods on the trait, but once the collection-reading method has returned, decoding should be complete.
Associated Types
type Error
The error type for method results.
Required Methods
fn read_nil(&mut self) -> Result<(), Self::Error>
Read a nil value.
fn read_usize(&mut self) -> Result<usize, Self::Error>
Read a usize value.
fn read_u64(&mut self) -> Result<u64, Self::Error>
Read a u64 value.
fn read_u32(&mut self) -> Result<u32, Self::Error>
Read a u32 value.
fn read_u16(&mut self) -> Result<u16, Self::Error>
Read a u16 value.
fn read_u8(&mut self) -> Result<u8, Self::Error>
Read a u8 value.
fn read_isize(&mut self) -> Result<isize, Self::Error>
Read a isize value.
fn read_i64(&mut self) -> Result<i64, Self::Error>
Read a i64 value.
fn read_i32(&mut self) -> Result<i32, Self::Error>
Read a i32 value.
fn read_i16(&mut self) -> Result<i16, Self::Error>
Read a i16 value.
fn read_i8(&mut self) -> Result<i8, Self::Error>
Read a i8 value.
fn read_bool(&mut self) -> Result<bool, Self::Error>
Read a bool value.
fn read_f64(&mut self) -> Result<f64, Self::Error>
Read a f64 value.
fn read_f32(&mut self) -> Result<f32, Self::Error>
Read a f32 value.
fn read_char(&mut self) -> Result<char, Self::Error>
Read a char value.
fn read_str(&mut self) -> Result<String, Self::Error>
Read a string value.
fn read_enum<T, F>(&mut self, name: &str, f: F) -> Result<T, Self::Error> where
F: FnOnce(&mut Self) -> Result<T, Self::Error>,
F: FnOnce(&mut Self) -> Result<T, Self::Error>,
Read an enumeration value.
name
indicates the enumeration type name. It may be used to sanity-check the data being read.f
is a function that will callread_enum_variant
(orread_enum_struct_variant
) to read the actual value.
fn read_enum_variant<T, F>(
&mut self,
names: &[&str],
f: F
) -> Result<T, Self::Error> where
F: FnMut(&mut Self, usize) -> Result<T, Self::Error>,
&mut self,
names: &[&str],
f: F
) -> Result<T, Self::Error> where
F: FnMut(&mut Self, usize) -> Result<T, Self::Error>,
Read an enumeration value.
names
is a list of the enumeration variant names.f
is a function that will callread_enum_variant_arg
orread_enum_struct_variant_field
as appropriate to read the associated values. It will be passed the index intonames
for the variant that is encoded.
fn read_enum_variant_arg<T, F>(
&mut self,
a_idx: usize,
f: F
) -> Result<T, Self::Error> where
F: FnOnce(&mut Self) -> Result<T, Self::Error>,
&mut self,
a_idx: usize,
f: F
) -> Result<T, Self::Error> where
F: FnOnce(&mut Self) -> Result<T, Self::Error>,
Read an unnamed data item for an enumeration variant.
This should only be called from a function passed to read_enum_variant
or read_enum_struct_variant
, and only when the index provided to that
function indicates that the variant has associated unnamed data. It
should be called once for each associated data item.
a_idx
is the (zero-based) index of the data item.f
is a function that will call the appropriate read method to deocde the data object.
Note that variant data items must be read in order - starting with index
0
and finishing with index len-1
. Implementations may use a_idx
,
the call order or both to select the correct data to decode.
fn read_enum_struct_variant<T, F>(
&mut self,
names: &[&str],
f: F
) -> Result<T, Self::Error> where
F: FnMut(&mut Self, usize) -> Result<T, Self::Error>,
&mut self,
names: &[&str],
f: F
) -> Result<T, Self::Error> where
F: FnMut(&mut Self, usize) -> Result<T, Self::Error>,
Read an enumeration value.
This is identical to read_enum_variant
, and is only provided for
symmetry with the Encoder
API.
fn read_enum_struct_variant_field<T, F>(
&mut self,
f_name: &str,
f_idx: usize,
f: F
) -> Result<T, Self::Error> where
F: FnOnce(&mut Self) -> Result<T, Self::Error>,
&mut self,
f_name: &str,
f_idx: usize,
f: F
) -> Result<T, Self::Error> where
F: FnOnce(&mut Self) -> Result<T, Self::Error>,
Read a named data item for an enumeration variant.
This should only be called from a function passed to read_enum_variant
or read_enum_struct_variant
, and only when the index provided to that
function indicates that the variant has associated named data. It should
be called once for each associated field.
f_name
is the name of the field.f_idx
is the (zero-based) index of the data item.f
is a function that will call the appropriate read method to deocde the data object.
Note that fields must be read in order - starting with index 0
and
finishing with index len-1
. Implementations may use f_idx
, f_name
,
the call order or any combination to choose the correct data to decode,
and may (but are not required to) return an error if these are
inconsistent.
fn read_struct<T, F>(
&mut self,
s_name: &str,
len: usize,
f: F
) -> Result<T, Self::Error> where
F: FnOnce(&mut Self) -> Result<T, Self::Error>,
&mut self,
s_name: &str,
len: usize,
f: F
) -> Result<T, Self::Error> where
F: FnOnce(&mut Self) -> Result<T, Self::Error>,
Read an struct value.
s_name
indicates the struct type name. It may be used to sanity-check the data being read.len
indicates the number of fields in the struct.f
is a function that will callread_struct_field
for each field in the struct.
fn read_struct_field<T, F>(
&mut self,
f_name: &str,
f_idx: usize,
f: F
) -> Result<T, Self::Error> where
F: FnOnce(&mut Self) -> Result<T, Self::Error>,
&mut self,
f_name: &str,
f_idx: usize,
f: F
) -> Result<T, Self::Error> where
F: FnOnce(&mut Self) -> Result<T, Self::Error>,
Read a field for a struct value.
This should only be called from a function passed to read_struct
. It
should be called once for each associated field.
f_name
is the name of the field.f_idx
is the (zero-based) index of the data item.f
is a function that will call the appropriate read method to deocde the data object.
Note that fields must be read in order - starting with index 0
and
finishing with index len-1
. Implementations may use f_idx
, f_name
,
the call order or any combination to choose the correct data to decode,
and may (but are not required to) return an error if these are
inconsistent.
fn read_tuple<T, F>(&mut self, len: usize, f: F) -> Result<T, Self::Error> where
F: FnOnce(&mut Self) -> Result<T, Self::Error>,
F: FnOnce(&mut Self) -> Result<T, Self::Error>,
Read a tuple value.
len
is the number of items in the tuple.f
is a function that will callread_tuple_arg
for each item in the tuple.
Note that external Decodable
implementations should not normally need
to use this method directly; it is meant for the use of this module's
own implementation of Decodable
for tuples.
fn read_tuple_arg<T, F>(&mut self, a_idx: usize, f: F) -> Result<T, Self::Error> where
F: FnOnce(&mut Self) -> Result<T, Self::Error>,
F: FnOnce(&mut Self) -> Result<T, Self::Error>,
Read a data item for a tuple.
This should only be called from a function passed to read_tuple
.
a_idx
is the (zero-based) index of the data item.f
is a function that will call the appropriate read method to encode the data object.
Note that tuple items must be read in order - starting with index 0
and finishing with index len-1
.
fn read_tuple_struct<T, F>(
&mut self,
s_name: &str,
len: usize,
f: F
) -> Result<T, Self::Error> where
F: FnOnce(&mut Self) -> Result<T, Self::Error>,
&mut self,
s_name: &str,
len: usize,
f: F
) -> Result<T, Self::Error> where
F: FnOnce(&mut Self) -> Result<T, Self::Error>,
Read a tuple struct value.
s_name
is the name of the tuple struct.len
is the number of items in the tuple struct.f
is a function that callsread_tuple_struct_arg
for each member.
fn read_tuple_struct_arg<T, F>(
&mut self,
a_idx: usize,
f: F
) -> Result<T, Self::Error> where
F: FnOnce(&mut Self) -> Result<T, Self::Error>,
&mut self,
a_idx: usize,
f: F
) -> Result<T, Self::Error> where
F: FnOnce(&mut Self) -> Result<T, Self::Error>,
Read a data item for a tuple struct.
This should only be called from a function passed to
read_tuple_struct
.
a_idx
is the (zero-based) index of the data item.f
is a function that will call the appropriate read method to encode the data object.
Note that tuple struct items must be read in order - starting with index
0
and finishing with index len-1
.
fn read_option<T, F>(&mut self, f: F) -> Result<T, Self::Error> where
F: FnMut(&mut Self, bool) -> Result<T, Self::Error>,
F: FnMut(&mut Self, bool) -> Result<T, Self::Error>,
Read an optional value.
f
is a function that will will be passed be passed false
if the
value is unset, and true
if it is set. If the function is passed
true
, it will call the appropriate read methods to read the associated
data type.
This method allows decoders 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 Decodable
implementations should not normally need
to use this method directly; it is meant for the use of this module's
own implementation of Decodable
for Option<T>
.
fn read_seq<T, F>(&mut self, f: F) -> Result<T, Self::Error> where
F: FnOnce(&mut Self, usize) -> Result<T, Self::Error>,
F: FnOnce(&mut Self, usize) -> Result<T, Self::Error>,
Read a sequence of values.
This should be used for both array-like ordered sequences and set-like unordered ones.
f
is a function that will be passed the length of the sequence, and will callread_seq_elt
for each value in the sequence.
fn read_seq_elt<T, F>(&mut self, idx: usize, f: F) -> Result<T, Self::Error> where
F: FnOnce(&mut Self) -> Result<T, Self::Error>,
F: FnOnce(&mut Self) -> Result<T, Self::Error>,
Read an element in the sequence.
This should only be called from a function passed to read_seq
.
idx
is the (zero-based) index of the value in the sequence.f
is a function that will call the appropriate read method to decode the data object.
Note that sequence elements must be read in order - starting with index
0
and finishing with index len-1
.
fn read_map<T, F>(&mut self, f: F) -> Result<T, Self::Error> where
F: FnOnce(&mut Self, usize) -> Result<T, Self::Error>,
F: FnOnce(&mut Self, usize) -> Result<T, Self::Error>,
Read an associative container (map).
f
is a function that will be passed the number of entries in the map, and will callread_map_elt_key
andread_map_elt_val
to decode each entry.
fn read_map_elt_key<T, F>(&mut self, idx: usize, f: F) -> Result<T, Self::Error> where
F: FnOnce(&mut Self) -> Result<T, Self::Error>,
F: FnOnce(&mut Self) -> Result<T, Self::Error>,
Read the key for an entry in a map.
This should only be called from a function passed to read_map
.
idx
is the (zero-based) index of the entry in the mapf
is a function that will call the appropriate read method to decode the key.
Note that map entries must be read in order - starting with index 0
and finishing with index len-1
- and for each entry, the key should be
read followed immediately by the value.
fn read_map_elt_val<T, F>(&mut self, idx: usize, f: F) -> Result<T, Self::Error> where
F: FnOnce(&mut Self) -> Result<T, Self::Error>,
F: FnOnce(&mut Self) -> Result<T, Self::Error>,
Read the value for an entry in a map.
This should only be called from a function passed to read_map
.
idx
is the (zero-based) index of the entry in the mapf
is a function that will call the appropriate read method to decode the value.
Note that map entries must be read in order - starting with index 0
and finishing with index len-1
- and for each entry, the key should be
read followed immediately by the value.
fn error(&mut self, err: &str) -> Self::Error
Record a decoding error.
This allows Decodable
implementations to report an error using a
Decoder
implementation's error type when inconsistent data is read.
For example, when reading a fixed-length array and the wrong length is
given by read_seq
.
Implementors
impl Decoder for Decoder type Error = DecoderError;