11 releases (4 breaking)
0.5.0 | Jul 25, 2024 |
---|---|
0.4.1 | Jun 13, 2024 |
0.3.0 | Mar 28, 2024 |
#1206 in Encoding
30 downloads per month
67KB
1.5K
SLoC
bin-proto
Simple & fast structured bit-level binary co/dec in Rust.
An improved and modernized fork of protocol. A more efficient but (slightly) less feature-rich alternative to deku.
This crate adds a trait (and a custom derive for ease-of-use) that can be
implemented on types, allowing structured data to be sent and received from any
binary stream. It is recommended to use
bitstream_io if you need
bit streams, as their BitRead
and BitWrite
traits are being used internally.
Example
Add this to your Cargo.toml
:
[dependencies]
bin-proto = "0.5"
And then define a type with the #[derive(bin_proto::ProtocolRead, bin_proto::ProtocolWrite)]
attributes.
use bin_proto::{ProtocolRead, ProtocolWrite, ProtocolNoCtx};
#[derive(Debug, ProtocolRead, ProtocolWrite, PartialEq)]
#[protocol(discriminant_type = "u8")]
#[protocol(bits = 4)]
enum E {
V1 = 1,
#[protocol(discriminant = "4")]
V4,
}
#[derive(Debug, ProtocolRead, ProtocolWrite, PartialEq)]
struct S {
#[protocol(bits = 1)]
bitflag: bool,
#[protocol(bits = 3)]
bitfield: u8,
enum_: E,
#[protocol(write_value = "self.arr.len() as u8")]
arr_len: u8,
#[protocol(tag = "arr_len as usize")]
arr: Vec<u8>,
#[protocol(tag(type = "u16", write_value = "self.prefixed_arr.len() as u16"))]
prefixed_arr: Vec<u8>,
#[protocol(flexible_array_member)]
read_to_end: Vec<u8>,
}
assert_eq!(
S::from_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::ByteOrder::BigEndian).unwrap(),
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],
}
);
You can implement Protocol
on your own types, and parse with context:
use bin_proto::{ProtocolRead, ProtocolWrite};
pub struct Ctx;
pub struct NeedsCtx;
impl ProtocolRead<Ctx> for NeedsCtx {
fn read(
_read: &mut dyn bin_proto::BitRead,
_byte_order: bin_proto::ByteOrder,
_ctx: &mut Ctx,
) -> bin_proto::Result<Self> {
// Use ctx here
Ok(Self)
}
}
impl ProtocolWrite<Ctx> for NeedsCtx {
fn write(
&self,
_write: &mut dyn bin_proto::BitWrite,
_byte_order: bin_proto::ByteOrder,
_ctx: &mut Ctx,
) -> bin_proto::Result<()> {
// Use ctx here
Ok(())
}
}
#[derive(ProtocolRead, ProtocolWrite)]
#[protocol(ctx = "Ctx")]
pub struct WithCtx(NeedsCtx);
WithCtx(NeedsCtx)
.bytes_ctx(bin_proto::ByteOrder::LittleEndian, &mut Ctx)
.unwrap();
Performance / Alternatives
This crate's main alternative is deku, and binrw for byte-level protocols.
bin-proto
is significantly faster than deku
in almost most of the tested scenarios.
The units for the below table are ns
, taken from
github CI.
You can find the benchmarks in the bench
directory.
Read enum |
Write enum |
Read Vec |
Write Vec |
Read IPv4 header | Write IPv4 header | |
---|---|---|---|---|---|---|
bin-proto |
29 | 62 | 1,327 | 557 | 173 | 138 |
deku |
1 | 92 | 582 | 937 | 3,234 | 633 |
Roadmap
The following features are planned:
- Bit/byte alignment
no_std
support (only afterbitstream_io
supports it)
Dependencies
~0.4–0.9MB
~20K SLoC