Crate bitcode_lightyear_patch

Bitcode is a crate for encoding and decoding using a tinier binary serialization strategy. You can easily go from having an object in memory, quickly serialize it to bytes, and then deserialize it back just as fast!

The format is not necessarily stable between versions. If you want a stable format, consider bincode.

Usage

// The object that we will encode.
let target: Vec<String> = vec!["a".to_owned(), "b".to_owned(), "c".to_owned()];

let encoded: Vec<u8> = bitcode::encode(&target).unwrap();
let decoded: Vec<String> = bitcode::decode(&encoded).unwrap();
assert_eq!(target, decoded);

Advanced Usage

Bitcode has several hints that can be applied. Hints may have an effect on the encoded length. Most importantly hints will never cause errors if they don’t hold true.

// We mark enum variants that are more likely with a higher frequency.
// This allows bitcode to use shorter encodings for them.
#[derive(Copy, Clone, bitcode::Encode, bitcode::Decode)]
enum Fruit {
    #[bitcode_hint(frequency = 10)]
    Apple,
    #[bitcode_hint(frequency = 5)]
    Banana,
    // Unspecified frequencies are 1.
    Blueberry,
    Lime,
    Lychee,
    Watermelon,
}

// A cart full of 16 apples takes 2 bytes to encode (1 bit per Apple).
let apple_cart: usize = bitcode::encode(&[Fruit::Apple; 16]).unwrap().len();
assert_eq!(apple_cart, 2);

// A cart full of 16 bananas takes 4 bytes to encode (2 bits per Banana).
let banana_cart: usize = bitcode::encode(&[Fruit::Banana; 16]).unwrap().len();
assert_eq!(banana_cart, 4);

// A cart full of 16 blueberries takes 8 bytes to encode (4 bits per Blueberry).
let blueberry_cart: usize = bitcode::encode(&[Fruit::Blueberry; 16]).unwrap().len();
assert_eq!(blueberry_cart, 8);

// We expect most user ages to be in the interval [10, 100), so we specify that as the expected
// range. If we're right most of the time, users will take fewer bits to encode.
#[derive(bitcode::Encode, bitcode::Decode)]
struct User {
    #[bitcode_hint(expected_range = "10..100")]
    age: u32
}

// A user with an age inside the expected range takes up to a byte to encode.
let expected_age: usize = bitcode::encode(&User { age: 42 }).unwrap().len();
assert_eq!(expected_age, 1);

// A user with an age outside the expected range takes more than 4 bytes to encode.
let unexpected_age: usize = bitcode::encode(&User { age: 31415926 }).unwrap().len();
assert!(unexpected_age > 4);

// We expect that most posts won't have that many views or likes, but some can. By using gamma
// encoding, posts with fewer views/likes will take fewer bits to encode.
#[derive(bitcode::Encode, bitcode::Decode)]
#[bitcode_hint(gamma)]
struct Post {
    views: u64,
    likes: u64,
}

// An average post just takes 1 byte to encode.
let average_post = bitcode::encode(&Post {
    views: 4,
    likes: 1,
}).unwrap().len();
assert_eq!(average_post, 1);

// A popular post takes 11 bytes to encode, luckily these posts are rare.
let popular_post = bitcode::encode(&Post {
    views: 27182818,
    likes: 161803,
}).unwrap().len();
assert_eq!(popular_post, 11)

Re-exports

• pub use buffer::Buffer;
• pub use crate::serde::deserialize;
• pub use crate::serde::serialize;

Modules

• buffer
• encoding
• read
• serde
• word
• word_buffer
• write

Structs

• Error
  Decoding / (De)serialization errors.

Traits

• Decode
  A type which can be decoded from bytes with decode.
• Encode
  A type which can be encoded to bytes with encode.

Functions

• decode
  Decodes a &[u8] into an instance of T: Decode.
• encode
  Encodes a T: Encode into a Vec<u8>.

Type Aliases

• Result

Derive Macros

• Decode
• Encode