Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/devashishdxt/nimble
Async friendly, simple and fast binary encoding and decoding in Rust
https://github.com/devashishdxt/nimble
binary encoding rust serialization
Last synced: 18 days ago
JSON representation
Async friendly, simple and fast binary encoding and decoding in Rust
- Host: GitHub
- URL: https://github.com/devashishdxt/nimble
- Owner: devashishdxt
- License: apache-2.0
- Created: 2020-02-02T18:32:16.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2022-04-13T06:54:27.000Z (almost 3 years ago)
- Last Synced: 2024-12-13T04:49:05.888Z (about 1 month ago)
- Topics: binary, encoding, rust, serialization
- Language: Rust
- Homepage:
- Size: 168 KB
- Stars: 23
- Watchers: 2
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE-APACHE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Nimble
[](https://github.com/devashishdxt/nimble/actions?query=workflow%3A%22Continuous+Integration%22)
[](https://crates.io/crates/nimble)
[](https://docs.rs/nimble)
[](https://github.com/devashishdxt/nimble/blob/master/LICENSE-MIT)
Async friendly, simple and fast binary encoding/decoding in Rust.
## Binary encoding scheme
This crate uses a minimal binary encoding scheme. For example, consider the following `struct`:
```rust
struct MyStruct {
a: u8,
b: u16,
}
```
`encode()` will serialize this into `Vec` of size `3` (which is the sum of sizes of `u8` and `u16`).
Similarly, for types which can have dynamic size (`Vec`, `String`, etc.), `encode()` prepends the size of encoded value
as `VarInt`.
## Usage
Add `nimble` in your `Cargo.toml`'s `dependencies` section:
```toml
[dependencies]
nimble = { version = "0.2", features = ["derive"] }
```
Or, if you are in an environment based on `tokio`, use:
```toml
[dependencies]
nimble = { version = "0.2", default-features = false, features = ["derive", "tokio"] }
```
For encoding and decoding, any type must implement two traits provided by this crate, i.e., `Encode` and `Decode`. For
convenience, `nimble` provides `derive` macros (only when `"derive"` feature is enabled) to implement these traits.
```rust
use nimble::{Encode, Decode};
#[derive(Encode, Decode)]
struct MyStruct {
a: u8,
b: u16,
}
```
Now you can use `encode()` and `decode()` functions to encode and decode values of `MyStruct`. In addition to this, you
can also use `MyStruct::encode_to()` function to encode values directly to a type implementing `AsyncWrite` and
`MyStruct::decode_from()` function to decode values directly from a type implementing `AsyncRead`.
> Note: Most of the functions exposed by this crate are `async` functions and returns `Future` values. So, you'll need
an executor to drive the `Future` returned from these functions. `async-std` and `tokio` are two popular options.
### Features
- `futures`: Select this feature when you want to implement `Encode` and `Decode` using `futures`'
`AsyncRead`/`AsyncWrite` traits.
- **Enabled** by default.
- `tokio`: Select this feature when you want to implement `Encode` and `Decode` using `tokio`'s `AsyncRead`/`AsyncWrite`
traits.
- **Disabled** by default.
- `derive`: Enables derive macros for implementing `Encode` and `Decode` traits.
- **Disabled** by default.
> Note: Features `futures` and `tokio` are mutually exclusive, i.e., only one of them can be enabled at a time.
> Compilation will fail if either both of them are enabled or none of them are enabled.
## License
Licensed under either of
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))
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.