binrw Documentation

binrw provides several capabilities for binary data handling:

• Declarative Parsing: Uses #[derive(BinRead)] and #[derive(BinWrite)] to generate parsers/serializers.
• Stream Support: Works with any source implementing std::io::Read or std::io::Write.
• Attribute Directives: Handles magic numbers, byte ordering (endianness), padding, alignment, and data validation directly in attributes.
• Reusable Types: Includes built-in types like NullString for null-terminated strings and FilePtr for data indirection via offsets.
• Extensibility: Supports parsing third-party types via custom free functions or value maps.
• Efficiency: Uses in-memory representations without requiring #[repr(C)] or #[repr(packed)].
• Ergonomics: Attribute code is written as actual Rust code (not strings), providing better IDE support.
• Environment: Supports no_std environments.

You can use attributes like #[br], #[bw], and #[brw] to apply directives for handling common binary data tasks such as:

• Endianness: e.g., #[br(little)] or #[br(big)].
• Magic Numbers: e.g., #[br(magic = b"SHAP")].
• Padding & Alignment: e.g., #[br(align_before = 0xA)].
• Counting: e.g., #[br(count = some_field)] to read a specific number of elements into a Vec.
• Assertions: e.g., #[brw(assert(condition))].
• Calculated values: e.g., #[bw(try_calc(expression))].

Directives can reference earlier fields by name. For tuple types, earlier fields are addressable using self_N, where N is the index of the field.

use binrw::{prelude::*, io::Cursor, NullString};

#[binrw]
#[brw(big, magic = b"DOG", assert(name.len() != 0))]
struct Dog {
    #[bw(try_calc(u8::try_from(bone_pile_count.len())))]
    bone_pile_count: u8,

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

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

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

Use pad_before, pad_after, align_before, align_after, and pad_size_to to manage data structure alignment.

• pad_before/pad_after: Skips a specific number of bytes.
• align_before/align_after: Aligns the next read/write to a specific byte boundary.
• pad_size_to: Ensures the reader/writer has advanced at least a certain number of bytes after the field is processed (useful for fixed-size buffers containing variable-length data).

Note on Writing: When writing, padding directives write zeroes to the padded region, overwriting existing bytes. To leave existing bytes untouched, use seek_before with an appropriate SeekFrom value instead.

#[derive(BinRead)]
struct MyType {
    #[br(align_before = 4, pad_after = 1, align_after = 4)]
    str: NullString,

    #[br(pad_size_to = 0x10)]
    test: u64,

    #[br(seek_before = SeekFrom::End(-4))]
    end: u32,
}

Named arguments allow passing data using key-value pairs, similar to a struct literal. This is useful for container objects like Vec or when you want to provide optional or unordered arguments.

• Syntax: Use curly braces {} for both import and args.
• Features: Supports field init shorthand (e.g., count instead of count: count) and optional arguments with default values (e.g., other: u16 = 0).
• Nesting: To nest named arguments, use the binrw::args! macro to construct the required argument object for the child.
• Manual Implementation: For types that manually implement BinRead or BinWrite, you can implement the binrw::NamedArgs trait to support this syntax.

# use binrw::prelude::*;
#[derive(BinRead)]
#[br(import {
    count: u32,
    other: u16 = 0 // optional argument
})]
struct Child {
    // ...
}

#[derive(BinRead)]
struct Parent {
    count: u32,

    #[br(args {
        count, // field init shorthand
        other: 5
    })]
    test: Child,

    #[br(args { count: 3 })]
    test2: Child,
}