Skip to content
A binary encoder / decoder implementation in Rust.
Rust
Branch: master
Clone or download

Latest commit

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows haha json go brrr (#324) May 23, 2020
examples 2nd implementation of the Config Trait (#214) Feb 8, 2018
src Reject trailing bytes (#198) May 26, 2020
tests Reject trailing bytes (#198) May 26, 2020
.gitignore rename doc functions (#208) Oct 10, 2017
.mailmap add mailmap entries Mar 16, 2020
Cargo.toml update author name to current legal name Mar 9, 2020
LICENSE.md Update LICENSE.md Sep 18, 2014
logo.png add logo Feb 15, 2015
readme.md Modernize CI (#311) Mar 24, 2020

readme.md

Bincode

CI

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

use serde::{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> = bincode::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 = bincode::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.
You can’t perform that action at this time.