Skip to content

poshcoe/bitcode

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Bitcode

Documentation crates.io Build

A binary encoder/decoder with the following goals:

  • 🔥 Blazingly fast
  • 🐁 Tiny serialized size
  • 💎 Highly compressible by Deflate/LZ4/Zstd

In contrast, these are non-goals:

  • Stable format across major versions
  • Self describing format
  • Compatibility with languages other than Rust

See rust_serialization_benchmark for benchmarks.

Example

use bitcode::{Encode, Decode};

#[derive(Encode, Decode, PartialEq, Debug)]
struct Foo<'a> {
    x: u32,
    y: &'a str,
}

let original = Foo {
    x: 10,
    y: "abc",
};

let encoded: Vec<u8> = bitcode::encode(&original); // No error
let decoded: Foo<'_> = bitcode::decode(&encoded).unwrap();
assert_eq!(original, decoded);

Library Example

Add bitcode to libraries without specifying the major version so binary crates can pick the version. This is a minimal stable subset of the bitcode API so avoid using any other functionality.

bitcode = { version = "0", features = ["derive"], default-features = false, optional = true }
#[cfg_attr(feature = "bitcode", derive(bitcode::Encode, bitcode::Decode))]
pub struct Vec2 {
    x: f32,
    y: f32,
}

Tuple vs Array

If you have multiple values of the same type:

  • Use a tuple or struct when the values are semantically different: x: u32, y: u32
  • Use an array when all values are semantically similar: pixels: [u8; 16]

Implementation Details

  • Heavily inspired by https://github.com/That3Percent/tree-buf
  • All instances of each field are grouped together making compression easier
  • Uses smaller integers where possible all the way down to 1 bit
  • Validation is performed up front on typed vectors before deserialization
  • Code is designed to be auto-vectorized by LLVM

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

About

A binary encoder/decoder for Rust

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Rust 100.0%