https://github.com/SoftbearStudios/bitcode

A binary encoder/decoder for Rust
https://github.com/SoftbearStudios/bitcode

rust rust-lang serde serialization

Last synced: 3 months ago
JSON representation

A binary encoder/decoder for Rust

• Host: GitHub
• URL: https://github.com/SoftbearStudios/bitcode
• Owner: SoftbearStudios
• License: mit
• Created: 2023-04-16T02:04:20.000Z (over 1 year ago)
• Default Branch: main
• Last Pushed: 2024-04-30T04:30:03.000Z (7 months ago)
• Last Synced: 2024-05-29T22:53:39.171Z (6 months ago)
• Topics: rust, rust-lang, serde, serialization
• Language: Rust
• Homepage: https://crates.io/crates/bitcode/
• Size: 302 KB
• Stars: 274
• Watchers: 9
• Forks: 13
• Open Issues: 7
• Metadata Files:
  • Readme: README.md
  • License: LICENSE-MIT

Awesome Lists containing this project

README

        
# Bitcode

[![Documentation](https://docs.rs/bitcode/badge.svg)](https://docs.rs/bitcode)

[![crates.io](https://img.shields.io/crates/v/bitcode.svg)](https://crates.io/crates/bitcode)

[![Build](https://github.com/SoftbearStudios/bitcode/actions/workflows/build.yml/badge.svg)](https://github.com/SoftbearStudios/bitcode/actions/workflows/build.yml)

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](https://github.com/djkoloski/rust_serialization_benchmark) for benchmarks.

## Example

```rust

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 = 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.

```toml

bitcode = { version = "0", features = ["derive"], default-features = false, optional = true }

```

```rust

#[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 

- 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

## `#![no_std]`

All `std`-only functionality is gated behind the (default) `"std"` feature.

`alloc` is required.

## License

Licensed under either of

* Apache License, Version 2.0

  ([LICENSE-APACHE](LICENSE-APACHE) or )

* MIT license

  ([LICENSE-MIT](LICENSE-MIT) or )

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.