Crate bin_proto 

Conversion to/from binary for arbitrary types. With no_std and no_alloc support.

For more information about #[derive(BitDecode, BitEncode)] and its attributes, see BitDecode or BitEncode.

Example

#[derive(Debug, BitDecode, BitEncode, PartialEq)]
#[bin_proto(discriminant_type = u8)]
#[bin_proto(bits = 4)]
enum E {
    V1 = 1,
    #[bin_proto(discriminant = 4)]
    V4,
}

#[derive(Debug, BitDecode, BitEncode, PartialEq)]
struct S {
    #[bin_proto(bits = 1)]
    bitflag: bool,
    #[bin_proto(bits = 3)]
    bitfield: u8,
    enum_: E,
    #[bin_proto(write_value = self.arr.len() as u8)]
    arr_len: u8,
    #[bin_proto(tag = arr_len as usize)]
    arr: Vec<u8>,
    #[bin_proto(tag_type = u16, tag_value = self.prefixed_arr.len() as u16)]
    prefixed_arr: Vec<u8>,
    #[bin_proto(untagged)]
    read_to_end: Vec<u8>,
}

assert_eq!(
    S::decode_bytes(&[
        0b1000_0000 // bitflag: true (1)
       | 0b101_0000 // bitfield: 5 (101)
           | 0b0001, // enum_: V1 (0001)
        0x02, // arr_len: 2
        0x21, 0x37, // arr: [0x21, 0x37]
        0x00, 0x01, 0x33, // prefixed_arr: [0x33]
        0x01, 0x02, 0x03, // read_to_end: [0x01, 0x02, 0x03]
    ], bin_proto::BigEndian).unwrap().0,
    S {
        bitflag: true,
        bitfield: 5,
        enum_: E::V1,
        arr_len: 2,
        arr: vec![0x21, 0x37],
        prefixed_arr: vec![0x33],
        read_to_end: vec![0x01, 0x02, 0x03],
    }
);

Manual Implementations

The BitDecode and BitEncode derive macros support the most common use-cases, but it may sometimes be necessary to manually implement BitEncode or BitDecode. Both traits have two generic parameters:

• Ctx: A mutable variable passed recursively down the codec chain
• Tag: A tag for specifying additional behavior

Tag can have any type. The following are used throughout bin-proto and ensure interoperability:

• Tag: Specifies that an additional tag is required during decoding, such as a length prefix for a Vec, or a discriminant of an enum
• Untagged: Specifies that the type has a tag used during decoding, but this tag is not written during encoding
• Bits: Specified that the type is a bitfield, and can have a variable number of bits

Features

• std — Enables support for types in the standard library.
• alloc — Enables support for types in the alloc crate.
• derive — Provides procedural macros for deriving traits BitEncode and BitDecode.
• prepend-tags — Enables tag prepending for common types (Option, str, etc.), removing the need for explicit tag specification for encoding/decoding. WARNING: length tags are encoded as usize, meaning they may vary if targets have different pointer widths.

Re-exports

pub extern crate bitstream_io;

Structs

BigEndian

Big-endian, or most significant bits first

Bits

A marker for BitDecode and BitEncode implementors that support bitfield operations.

LittleEndian

Little-endian, or least significant bits first

Tag

A marker for BitDecode implementors that require a tag.

Untagged

A marker for BitEncode implementors that don’t prepend their tag, and BitDecode implementors that usually have a tag, but can be read to EOF

Enums

Error

Traits

BitCodec

A trait with helper functions for simple codecs.

BitDecode

A trait for bit-level decoding.

BitDecodeExt

Utility functionality for bit-level decoding.

BitEncode

A trait for bit-level encoding.

BitEncodeExt

Utility functionality for bit-level encoding.

BitRead

A trait for anything that can read a variable number of potentially un-aligned values from an input stream

BitWrite

A trait for anything that can write a variable number of potentially un-aligned values to an output stream

Discriminable

A trait for types with discriminants. Automatically derived for enums.

Endianness

A stream’s endianness, or byte order, for determining how bits should be read.

Type Aliases

Result

Alias for a Result with the error type Error.

Derive Macros

BitDecodederive

Derive the BitDecode and BitEncode traits.

BitEncodederive

Derive the BitDecode and BitEncode traits.