binread

BinRead allows you to declaratively define binary parsing logic for Rust structs using the BinRead derive macro. You can use attributes starting with #[br(...)] to specify magic numbers, assertions, endianness, counts for collections, and alignment requirements.

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

Both the #[derive(BinRead)] and #[binread] macros support custom attributes to control how fields are parsed. You can use the following attribute prefixes:

• binread
• br

These attributes are used to define parsing behavior, such as marking fields as temporary or specifying custom parsing logic. The macro will automatically clean up these attributes so they do not interfere with the rest of your code after expansion.

To avoid long import lists, use the binread::prelude module, which exports the most commonly used traits and types:

• BinRead
• BinReaderExt
• BinResult

The BinRead trait defines how a type is read from a byte stream. It is implemented for most primitives and simple collections.

Core Methods

• read<R: Read + Seek>(reader: &mut R) -> BinResult<Self>: A simple shortcut that assumes no arguments are needed (Args = ()). It panics if args_default() is not implemented.
• read_args<R: Read + Seek>(reader: &mut R, args: Self::Args) -> BinResult<Self>: Reads the type using the provided arguments.
• read_options<R: Read + Seek>(reader: &mut R, options: &ReadOptions, args: Self::Args) -> BinResult<Self>: The primary method for reading with specific configuration (like endianness) and arguments.

Associated Types

• type Args: Any + Copy: The type of arguments required to parse this type. For types that require no arguments, use the unit type ().

If a parsing error was triggered by a Custom variant, you can attempt to downcast the contained error to a specific type using the custom_err<T>() method. This is useful when you want to pass specific error context from your own logic through the binread error pipeline.

Returns Some(&T) if the error is a Custom variant and matches the requested type T, otherwise returns None.

// Example of retrieving a custom error type
if let Err(e) = result {
    if let Some(my_err) = e.custom_err::<MySpecificError>() {
        println!("Caught specific error: {:?}", my_err);
    }
}

Both NullString and NullWideString provide methods to convert their internal byte/word buffers into standard Rust String types:

• into_string(): Returns a String using lossy conversion (String::from_utf8_lossy for NullString and String::from_utf16_lossy for NullWideString). This is useful when you want to ensure the conversion succeeds even if the binary data contains invalid UTF sequences.
• into_string_lossless(): Returns a Result<String, E>, where E is the specific error type for the encoding (FromUtf8Error or FromUtf16Error). This is preferred when you need to handle invalid encoding as an error.

NullWideString is a specialized type for reading null-terminated UTF-16 (wide) strings. It reads u16 values until a 0u16 is encountered.

Note: This type is endian-dependent on a per-character basis. You must use the appropriate endianness method (e.g., read_le or read_be) when reading from the stream. The null terminator is consumed from the reader but not included in the data.

You can convert the result into a String using into_string() (lossy UTF-16 conversion) or into_string_lossless() (returns a Result).

use binread::{BinRead, BinReaderExt, NullWideString, io::Cursor};

const WIDE_STRINGS: &[u8] = b"w\0i\0d\0e\0 \0s\0t\0r\0i\0n\0g\0s\0\0\0";

let mut wide_strings = Cursor::new(WIDE_STRINGS);

// Use read_le for little-endian wide strings
assert_eq!(
    wide_strings.read_le::<NullWideString>().unwrap().into_string(),
    "wide strings"
);

The #[binread] attribute macro provides an alternative way to apply binread logic to a type. It functions similarly to the BinRead derive macro but is implemented as an attribute macro, which can be useful for more complex transformations or when specific attribute processing is required during the parsing phase.

#[binread]
struct MyData {
    field1: u32,
    field2: u8,
}