Module bendy::encoder

An encoder for bencode. Guarantees that the output string is valid bencode

Encoding a structure

The easiest way to encode a structure is to implement Encodable for it. For most structures, this should be very simple:

struct Message {
   foo: i32,
   bar: String,
}

impl Encodable for Message {
    // Atoms have depth one. The struct wrapper adds one level to that
    const MAX_DEPTH: usize = 1;

    fn encode(&self, encoder: SingleItemEncoder) -> Result<(), Error> {
        encoder.emit_dict(|mut e| {
            // Use e to emit the values
            e.emit_pair(b"bar", &self.bar)?;
            e.emit_pair(b"foo", &self.foo)
        })
    }
}

Then, messages can be serialized using Encodable::to_bytes:

Message{
    foo: 1,
    bar: "quux".to_string(),
}.to_bytes()

Most primitive types already implement Encodable.

Nesting depth limits

To allow this to be used on limited platforms, all implementations of Encodable include a maximum nesting depth. Atoms (integers and byte strings) are considered to have depth 0. An object (a list or dict) containing only atoms has depth 1, and in general, an object has a depth equal to the depth of its deepest member plus one. In some cases, an object doesn't have a statically known depth. For example, ASTs may be arbitrarily nested. Such objects should have their depth set to 0, and callers should construct the Encoder manually, adding an appropriate buffer for the depth:

let mut encoder = Encoder::new()
    .with_max_depth(ObjectType::MAX_DEPTH + 10);
encoder.emit(object)?;
encoder.get_output()

Error handling

Once an error occurs during encoding, all future calls to the same encoding stream will fail early with the same error. It is not defined whether any callback or implementation of Encodable::encode is called before returning an error; such callbacks should respond to failure by bailing out as quickly as possible.

Not all values in Error can be caused by an encoding operation. Specifically, you only need to worry about UnsortedKeys and NestingTooDeep.

Structs

AsString	Wrapper to allow Vec<u8> encoding as bencode string element.
Encoder	The actual encoder. Unlike the decoder, this is not zero-copy, as that would result in a horrible interface
SingleItemEncoder	An encoder that can only encode a single item. See Encoder for usage examples; the only difference between these classes is that SingleItemEncoder can only be used once.
SortedDictEncoder	Encodes a map with pre-sorted keys
UnsortedDictEncoder	Helper to write a dictionary that may have keys out of order. This will buffer the dict values in temporary memory, then sort them before adding them to the serialized stream

Traits

Encodable	An object that can be encoded into a single bencode object
PrintableInteger	A value that can be formatted as a decimal integer