#binary #encode #decode #serialize #deserialize

bincode

A binary serialization / deserialization strategy that uses Serde for transforming structs into bytes and vice versa!

52 releases (4 stable)

new 1.1.2 Feb 16, 2019
1.0.1 Jun 18, 2018
1.0.0 Feb 15, 2018
1.0.0-alpha7 Apr 8, 2017
0.0.2 Nov 24, 2014

#6 in Network programming

Download history 16191/week @ 2018-11-03 16181/week @ 2018-11-10 14787/week @ 2018-11-17 15461/week @ 2018-11-24 17380/week @ 2018-12-01 17816/week @ 2018-12-08 16692/week @ 2018-12-15 12288/week @ 2018-12-22 14258/week @ 2018-12-29 17732/week @ 2019-01-05 19960/week @ 2019-01-12 19743/week @ 2019-01-19 19929/week @ 2019-01-26 19743/week @ 2019-02-02 27451/week @ 2019-02-09

77,543 downloads per month
Used in 380 crates (255 directly)

MIT license

68KB
2K SLoC

Bincode

Build Status

A compact encoder / decoder pair that uses a binary zero-fluff encoding scheme. The size of the encoded object will be the same or smaller than the size that the object takes up in memory in a running Rust program.

In addition to exposing two simple functions (one that encodes to Vec<u8>, and one that decodes from &[u8]), binary-encode exposes a Reader/Writer API that makes it work perfectly with other stream-based apis such as rust files, network streams, and the flate2-rs compression library.

Api Documentation

Bincode in the wild

  • google/tarpc: Bincode is used to serialize and deserialize networked RPC messages.
  • servo/webrender: Bincode records webrender API calls for record/replay-style graphics debugging.
  • servo/ipc-channel: Ipc-Channel uses Bincode to send structs between processes using a channel-like API.

Example

#[macro_use]
extern crate serde_derive;
extern crate bincode;

use bincode::{serialize, deserialize};

#[derive(Serialize, Deserialize, PartialEq, Debug)]
struct Entity {
    x: f32,
    y: f32,
}

#[derive(Serialize, Deserialize, PartialEq, Debug)]
struct World(Vec<Entity>);

fn main() {
    let world = World(vec![Entity { x: 0.0, y: 4.0 }, Entity { x: 10.0, y: 20.5 }]);

    let encoded: Vec<u8> = serialize(&world).unwrap();

    // 8 bytes for the length of the vector, 4 bytes per float.
    assert_eq!(encoded.len(), 8 + 4 * 4);

    let decoded: World = deserialize(&encoded[..]).unwrap();

    assert_eq!(world, decoded);
}

Details

The encoding (and thus decoding) proceeds unsurprisingly -- primitive types are encoded according to the underlying Writer, tuples and structs are encoded by encoding their fields one-by-one, and enums are encoded by first writing out the tag representing the variant and then the contents.

However, there are some implementation details to be aware of:

  • isize/usize are encoded as i64/u64, for portability.
  • enums variants are encoded as a u32 instead of a usize. u32 is enough for all practical uses.
  • str is encoded as (u64, &[u8]), where the u64 is the number of bytes contained in the encoded string.

Dependencies

~429KB