https://github.com/jam1garner/binrw

A Rust crate for helping parse and rebuild binary data using ✨macro magic✨.
https://github.com/jam1garner/binrw

Last synced: 4 days ago
JSON representation

A Rust crate for helping parse and rebuild binary data using ✨macro magic✨.

• Host: GitHub
• URL: https://github.com/jam1garner/binrw
• Owner: jam1garner
• License: mit
• Created: 2020-10-31T19:19:07.000Z (about 4 years ago)
• Default Branch: master
• Last Pushed: 2024-12-01T07:41:19.000Z (about 1 month ago)
• Last Synced: 2025-01-03T02:53:58.532Z (5 days ago)
• Language: Rust
• Homepage: https://binrw.rs
• Size: 1.47 MB
• Stars: 654
• Watchers: 9
• Forks: 39
• Open Issues: 28
• Metadata Files:
  • Readme: README.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# binrw

[![crates](https://img.shields.io/crates/v/binrw.svg)](https://crates.io/crates/binrw)

[![tests](https://github.com/jam1garner/binrw/actions/workflows/main.yml/badge.svg)](https://github.com/jam1garner/binrw/actions/workflows/main.yml)

[![docs.rs](https://docs.rs/binrw/badge.svg)](https://docs.rs/binrw)

[![codecov](https://codecov.io/gh/jam1garner/binrw/branch/master/graph/badge.svg?token=UREOWI2KAY)](https://codecov.io/gh/jam1garner/binrw) 

[![discord](https://img.shields.io/discord/818723403871551509?color=gray&label=%20&logo=discord)](https://discord.gg/ABy4Qh549j)

[![matrix: #binrw:matrix.org](https://img.shields.io/badge/style-%23binrw:matrix.org-blue.svg?style=flat&label=[m])](https://matrix.to/#/#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](https://docs.rs/binrw/latest/binrw/docs/attribute)

  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](https://docs.rs/binrw/latest/binrw/struct.NullString.html) and

  [data indirection using offsets](https://docs.rs/binrw/latest/binrw/struct.FilePtr.html)

* Parses types from third-party crates using

  [free functions](https://docs.rs/binrw/latest/binrw/docs/attribute#custom-parsers)

  or [value maps](https://docs.rs/binrw/latest/binrw/docs/attribute#map)

* 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

```rust

#[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,

    #[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](https://docs.rs/binrw).