docs.rs failed to build rmp-0.3.1
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.

Visit the last successful build: rmp-0.8.14

RMP - Rust MessagePack

RMP is a pure Rust MessagePack implementation.

Usage

To use rmp, first add this to your Cargo.toml:

[dependencies.rmp]
rmp = "0.3.0"

Then, add this to your crate root:

extern crate rmp as msgpack;

Features

Convenient API

RMP is designed to be lightweight and straightforward. There are low-level API, which gives you full control on data encoding/decoding process and makes no heap allocations. On the other hand there are high-level API, which provides you convenient interface using Rust standard library and compiler reflection, allowing to encode/decode structures using derive attribute.
Clear error handling

RMP's error system guarantees that you never receive an error enum with unreachable variant.
Robust and tested

This project is developed using TDD and CI, so any found bugs will be fixed without breaking existing functionality.

Examples

Let's try to encode a tuple of int and string.

extern crate rmp as msgpack;
extern crate rustc_serialize;

use rustc_serialize::Encodable;
use msgpack::Encoder;

fn main() {
    let val = (42u8, "the Answer");

    // The encoder borrows the bytearray buffer.
    let mut buf = [0u8; 13];

    val.encode(&mut Encoder::new(&mut &mut buf[..]));

    assert_eq!([0x92, 0x2a, 0xaa, 0x74, 0x68, 0x65, 0x20, 0x41, 0x6e, 0x73, 0x77, 0x65, 0x72], buf);
}

Now we have an encoded buffer, which we can decode the same way:

extern crate rmp as msgpack;
extern crate rustc_serialize;

use rustc_serialize::Decodable;
use msgpack::Decoder;

fn main() {
    let buf = [0x92, 0x2a, 0xaa, 0x74, 0x68, 0x65, 0x20, 0x41, 0x6e, 0x73, 0x77, 0x65, 0x72];

    let mut decoder = Decoder::new(&buf[..]);

    let res: (u8, String) = Decodable::decode(&mut decoder).unwrap();

    assert_eq!((42u8, "the Answer".to_string()), res);
}

RMP also allows to automatically serialize/deserialize custom structures using rustc_serialize reflection. To enable this feature, derive RustcEncodable and RustcDecodable attributes as shown in the following example:

extern crate rmp as msgpack;
extern crate rustc_serialize;

use rustc_serialize::{Encodable, Decodable};
use msgpack::{Encoder, Decoder};

#[derive(RustcEncodable, RustcDecodable, PartialEq, Debug)]
struct Custom {
    id: u32,
    key: String,
}

fn main() {
    let val = Custom { id: 42u32, key: "the Answer".to_string() };

    let mut buf = [0u8; 13];

    val.encode(&mut Encoder::new(&mut &mut buf[..]));

    assert_eq!([0x92, 0x2a, 0xaa, 0x74, 0x68, 0x65, 0x20, 0x41, 0x6e, 0x73, 0x77, 0x65, 0x72], buf);

    // Now try to unpack the buffer into the initial struct.
    let mut decoder = Decoder::new(&buf[..]);
    let res: Custom = Decodable::decode(&mut decoder).ok().unwrap();

    assert_eq!(val, res);
}

Limitations and plans

Non-owning ValueRef variant, which can be created from [u8], Cursor<[u8]> etc. and borrows data from it, which makes it absolute zero-copy.

Versioning

This project adheres to Semantic Versioning. However until 1.0.0 comes there will be the following rules: