Crate nimble

Nimble

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:

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

Usage

Add nimble in your Cargo.toml’s dependencies section:

[dependencies]
nimble = { version = "0.2", features = ["derive"] }

Or, if you are in an environment based on tokio, use:

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

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.

Modules

io

Re-exports IO traits from tokio/futures depending on enabled feature.

Structs

Config

Encoding/decoding configuration

Enums

Endianness

Endianness of encoded bytes

Error

Error returned by this crate

Traits

Decode

Trait for decoding values

Encode

Trait for encoding values

Functions

config

Returns default Config

decode

Decodes a value from bytes using default configuration

decode_from

Decodes values from reader

encode

Encodes a value in a Vec using default configuration

encode_to

Writes encoded byte array to writer and returns the number of bytes written

Type Aliases

Result

Result type with nimble::Error

Attribute Macros

async_trait

Utility macro for implementing Encode and Decode traits.