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

The error type for method results.

Required Methods

Read a nil value.

Read a usize value.

Read a u64 value.

Read a u32 value.

Read a u16 value.

Read a u8 value.

Read a isize value.

Read a i64 value.

Read a i32 value.

Read a i16 value.

Read a i8 value.

Read a bool value.

Read a f64 value.

Read a f32 value.

Read a char value.

Read a string value.

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.

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.

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.

Read an enumeration value.

This is identical to read_enum_variant, and is only provided for symmetry with the Encoder API.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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