Trait rustc_serialize::Decoder

pub trait Decoder {
    type Error;

    // Required methods
    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.

Required 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>,

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 call read_enum_variant (or read_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>,

Read an enumeration value.

• names is a list of the enumeration variant names.
• f is a function that will call read_enum_variant_arg or read_enum_struct_variant_field as appropriate to read the associated values. It will be passed the index into names 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>,

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

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

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

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 call read_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>,

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

Read a tuple value.

• len is the number of items in the tuple.
• f is a function that will call read_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>,

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

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 calls read_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>,

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

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

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 call read_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>,

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

Read an associative container (map).

• f is a function that will be passed the number of entries in the map, and will call read_map_elt_key and read_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>,

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 map
• f 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>,

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 map
• f 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