A bitwise encoder/decoder similar to bincode, which attempts to shrink the serialized size without sacrificing speed (as would be the case with compression).
The format may change between major versions, so we are free to optimize it.
Comparison with bincode
- Bitwise serialization
- Gamma encoded lengths and enum variant indices
- Enums use the fewest possible bits, e.g. an enum with 4 variants uses 2 bits
- Apply attributes to fields/enum variants:
| Attribute | Type | Result |
|---|---|---|
#[bitcode_hint(ascii)] |
String | Uses 7 bits per character |
#[bitcode_hint(ascii_lowercase)] |
String | Uses 5 bits per character |
#[bitcode_hint(expected_range = "50..100"] |
u8-u64 | Uses log2(range.end - range.start) bits |
#[bitcode_hint(expected_range = "0.0..1.0"] |
f32/f64 | Uses ~25 bits for f32 and ~54 bits for f64 |
#[bitcode_hint(frequency = 123) |
enum variant | Frequent variants use fewer bits (see Huffman coding) |
#[bitcode_hint(gamma)] |
i8-i64/u8-u64 | Small integers use fewer bits (see Elias gamma coding) |
#[bitcode(with_serde)] |
T: Serialize | Uses serde::Serialize instead of bitcode::Encode |
- Doesn't support streaming APIs
- Format may change between major versions
- With
feature = "derive", types containing themselves must use#[bitcode(recursive)]to compile
| Type | Bitcode (derive) | Bitcode (serde) | Bincode | Bincode (varint) | Postcard |
|---|---|---|---|---|---|
| bool | 1 | 1 | 8 | 8 | 8 |
| u8/i8 | 8 | 8 | 8 | 8 | 8 |
| u16/i16 | 16 | 16 | 16 | 8-24 | 8-24 |
| u32/i32 | 32 | 32 | 32 | 8-40 | 8-40 |
| u64/i64 | 64 | 64 | 64 | 8-72 | 8-80 |
| u128/i128 | 128 | 128 | 128 | 8-136 | 8-152 |
| usize/isize | 64 | 64 | 64 | 8-72 | 8-80 |
| f32 | 32 | 32 | 32 | 32 | 32 |
| f64 | 64 | 64 | 64 | 64 | 64 |
| char | 21 | 21 | 8-32 | 8-32 | 16-40 |
| Option<()> | 1 | 1 | 8 | 8 | 8 |
| Result<(), ()> | 1 | 1-3 | 32 | 8 | 8 |
| enum { A, B, C, D } | 2 | 1-5 | 32 | 8 | 8 |
| Duration | 94 | 96 | 96 | 16-112 | 16-120 |
Note: These are defaults, and can be optimized with hints in the case of Bitcode (derive) or custom impl Serialize in the case of serde serializers.
| Value | Bitcode (derive) | Bitcode (serde) | Bincode | Bincode (varint) | Postcard |
|---|---|---|---|---|---|
| [true; 4] | 4 | 4 | 32 | 32 | 32 |
| vec![(); 0] | 1 | 1 | 64 | 8 | 8 |
| vec![(); 1] | 3 | 3 | 64 | 8 | 8 |
| vec![(); 256] | 17 | 17 | 64 | 24 | 16 |
| vec![(); 65536] | 33 | 33 | 64 | 40 | 24 |
| "" | 1 | 1 | 64 | 8 | 8 |
| "abcd" | 37 | 37 | 96 | 40 | 40 |
| "abcd1234" | 71 | 71 | 128 | 72 | 72 |
Random Structs and Enums (average size and speed)
| Format | Size (bytes) | Serialize (ns) | Deserialize (ns) |
|---|---|---|---|
| Bitcode (derive) | 6.2 | 14 | 50 |
| Bitcode (serde) | 6.7 | 18 | 59 |
| Bincode | 20.3 | 17 | 61 |
| Bincode (varint) | 10.9 | 26 | 68 |
| Bincode (LZ4) | 9.9 | 58 | 73 |
| Bincode (Deflate Fast) | 8.4 | 336 | 279 |
| Bincode (Deflate Best) | 7.8 | 1990 | 275 |
| Postcard | 10.7 | 21 | 57 |
Some test cases were derived from bincode (see comment in tests.rs).
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
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.