#binary #encode #decode #serialize #deserialize

binrw

A Rust crate for helping read structs from binary data using ✨macro magic✨

21 unstable releases

0.11.2 May 15, 2023
0.11.1 Feb 5, 2023
0.10.0 Sep 17, 2022
0.9.2 Jul 1, 2022
0.1.0 Sep 12, 2020

#31 in Encoding

Download history 2245/week @ 2023-02-09 2382/week @ 2023-02-16 2059/week @ 2023-02-23 1948/week @ 2023-03-02 2051/week @ 2023-03-09 2288/week @ 2023-03-16 2753/week @ 2023-03-23 3116/week @ 2023-03-30 3434/week @ 2023-04-06 3367/week @ 2023-04-13 3413/week @ 2023-04-20 4513/week @ 2023-04-27 3998/week @ 2023-05-04 4738/week @ 2023-05-11 4337/week @ 2023-05-18 3274/week @ 2023-05-25

17,206 downloads per month
Used in 43 crates (37 directly)

MIT license

185KB
4K SLoC

binrw

crates tests docs.rs codecov discord matrix: #binrw:matrix.org

binrw helps you write maintainable & easy-to-read declarative binary data readers and writers using ✨macro magic✨.

Features

  • Generates efficient data parsers and serialisers for structs and enums using #[derive]
  • Reads and writes data from any source using standard io::Read and io::Write streams
  • Directives in attributes handle common binary parsing tasks like matching magic numbers, byte ordering, padding & alignment, data validation, and more
  • Includes reusable types for common data structures like null-terminated strings and data indirection using offsets
  • Parses types from third-party crates using free functions or value maps
  • Uses efficient in-memory representations (does not require #[repr(C)] or #[repr(packed)])
  • Code in attributes is written as code, not as strings, for improved ergonomics and first-class IDE support
  • Supports no_std

Usage

#[derive(BinRead)]
#[br(magic = b"DOG", assert(name.len() != 0))]
struct Dog {
    bone_pile_count: u8,

    #[br(big, count = bone_pile_count)]
    bone_piles: Vec<u16>,

    #[br(align_before = 0xA)]
    name: NullString
}

let mut reader = Cursor::new(b"DOG\x02\x00\x01\x00\x12\0\0Rudy\0");
let dog: Dog = reader.read_ne().unwrap();
assert_eq!(dog.bone_piles, &[0x1, 0x12]);
assert_eq!(dog.name.into_string(), "Rudy")

For more information, including a more detailed overview of binrw, visit the documentation.

Dependencies

~1–1.4MB
~32K SLoC