[][src]Crate binread

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

Example

 
#[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")

The Basics

At the core of binread is the BinRead trait. It defines how to read a type from bytes and is already implemented for most primitives and simple collections.

use binread::BinRead;
use std::io::Cursor;
 
let mut reader = Cursor::new(b"\0\0\0\x01");
let val = u32::read(&mut reader).unwrap();

However, read is intentionally simple and, as a result, doesn't even allow you to configure the byte order. For that you need read_options which, while more powerful, isn't exactly ergonomics.

So, as a balance between ergonomics and configurability you have the BinReaderExt trait. It is an extension for readers to allow for you to directly read any BinRead types from any reader.

Example:

use binread::{BinReaderExt, io::Cursor};
 
let mut reader = Cursor::new(b"\x00\x0A");
let val: u16 = reader.read_be().unwrap();
assert_eq!(val, 10);

It even works for tuples and arrays of BinRead types for up to size 32.

Derive Macro

The most significant feature of binread is its ability to use the Derive macro to implement BinRead for your own types. This allows you to replace repetitive imperative code with declarative struct definitions for your binary data parsing.

Basic Derive Example

#[derive(BinRead)]
struct MyType {
    first: u32,
    second: u32
}
 
// Also works with tuple types!
#[derive(BinRead)]
struct MyType2(u32, u32);

Attributes

The BinRead derive macro uses attributes in order to allow for more complicated parsers. For example you can use big or little at either the struct-level or the field-level in order to override the byte order of values.

#[derive(BinRead)]
#[br(little)]
struct MyType (
    #[br(big)] u32, // will be big endian
    u32, // will be little endian
);

The order of precedence is: (from highed to lowest)

  1. Field-level
  2. Variant-level (for enums)
  3. Top-level
  4. Configured (i.e. what endianess was passed in)
  5. Native endianess

For a list of attributes see the attribute module

Modules

attribute

A documentation-only module for attributes

endian

An enum to represent what endianness to read as

error

Error types and internal error handling functions

file_ptr

A wrapper type for representing a layer of indirection within a file.

io

A swappable version of std::io that works in no_std + alloc environments. If the feature flag std is enabled (as it is by default), this will just re-export types from std::io.

prelude

The collection of traits and types you'll likely need when working with binread and are unlikely to cause name conflicts.

Structs

FilePtr

A wrapper type for representing a layer of indirection within a file.

NullString

A null terminated UTF-8 string designed to make reading any null-terminated data easier.

NullWideString

A null terminated UTF-16 string designed to make reading any 16 bit wide null-terminated data easier.

PosValue

A wrapper where the position it was read from is stored alongside the value

ReadOptions

Runtime-configured options for reading the type using BinRead

Enums

Endian

An enum to represent what endianness to read as

Error

An error while parsing a BinRead type

Traits

BinRead

A BinRead trait allows reading a structure from anything that implements io::Read and io::Seek BinRead is implemented on the type to be read out of the given reader

BinReaderExt

An extension trait for io::Read to provide methods for reading a value directly

Type Definitions

BinResult

A Result for any binread function that can return an error

FilePtr8

Type alias for 8-bit pointers

FilePtr16

Type alias for 16-bit pointers

FilePtr32

Type alias for 32-bit pointers

FilePtr64

Type alias for 64-bit pointers

FilePtr128

Type alias for 128-bit pointers

Derive Macros

BinRead

Derive macro for BinRead. Usage here.