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

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

- [src]
  `impl Decoder for Decoder type Error = DecoderError;`

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)