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

Emit an enumeration value.

- `name` indicates the enumeration type name.
- `f` is a function that will call `emit_enum_variant` or `emit_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>,`

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 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 call `emit_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>,`

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

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 call `emit_enum_struct_variant_field` 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,
        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>,`

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

Emit a struct value.

- `name` is the name of the struct.
- `len` is the number of members.
- `f` is a function that calls `emit_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>,`

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

Emit a tuple value.

- `len` is the number of items in the tuple.
- `f` is a function that calls `emit_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>,`

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

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 calls `emit_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>,`

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

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

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

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 call `emit_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>,`

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

Emit an associative container (map).

- `len` is the number of entries in the map.
- `f` is a function that will call `emit_map_elt_key` and `emit_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>,`

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

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

- [src]
  `impl<'a> Encoder for Encoder<'a> type Error = EncoderError;`

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