Module binrw::docs::attribute

Expand description

Glossary of directives in binrw attributes (#[br], #[bw], #[brw]).

View for: #[br] #[bw] Both

List of directives

r/w	Directive	Supports*	Description
rw	`align_after`	field	Aligns the readerwriter to the Nth byte after a field.
rw	`align_before`	field	Aligns the readerwriter to the Nth byte before a field.
rw	`args`	field	Passes arguments to another binrw object.
rw	`args_raw`	field	Like `args`, but specifies a single variable containing the arguments.
rw	`assert`	struct, field, non-unit enum, data variant	Asserts that a condition is true. Can be used multiple times.
rw	`big`	all except unit variant	Sets the byte order to big-endian.
rw	`calc`	field	Computes the value of a field instead of reading datausing a field.
r	`count`	field	Sets the length of a vector.
r	`dbg`	field	Prints the value and offset of a field to `stderr`.
r	`default`	field	An alias for `ignore`.
r	`err_context`	field	Adds additional context to errors.
rw	`if`	field	Reads or writesReadsWrites data only if a condition is true.
rw	`ignore`	field	For `BinRead`, uses the `default` value for a field instead of reading data. For `BinWrite`, skips writing the field.Uses the `default` value for a field instead of reading data.Skips writing the field.
rw	`import`	struct, non-unit enum, unit-like enum	Defines extra arguments for a struct or enum.
rw	`import_raw`	struct, non-unit enum, unit-like enum	Like `import`, but receives the arguments as a single variable.
rw	`is_big`	field	Conditionally sets the byte order to big-endian.
rw	`is_little`	field	Conditionally set the byte order to little-endian.
rw	`little`	all except unit variant	Sets the byte order to little-endian.
rw	`magic`	all	MatchesWrites a magic number.
rw	`map`	all except unit variant	Maps an object or value to a new value.
rw	`map_stream`	all except unit variant	Maps the readwrite stream to a new stream.
r	`offset`	field	Modifies the offset used by a `FilePtr` while parsing.
rw	`pad_after`	field	Skips N bytes after readingwriting a field.
rw	`pad_before`	field	Skips N bytes before readingwriting a field.
rw	`pad_size_to`	field	Ensures the readerwriter is always advanced at least N bytes.
r	`parse_with`	field	Specifies a custom function for reading a field.
r	`pre_assert`	struct, non-unit enum, unit variant	Like `assert`, but checks the condition before parsing.
rw	`repr`	unit-like enum	Specifies the underlying type for a unit-like (C-style) enum.
rw	`restore_position`	field	Restores the reader’swriter’s position after readingwriting a field.
r	`return_all_errors`	non-unit enum	Returns a `Vec` containing the error which occurred on each variant of an enum on failure. This is the default.
r	`return_unexpected_error`	non-unit enum	Returns a single generic error on failure.
rw	`seek_before`	field	Moves the readerwriter to a specific position before readingwriting data.
rw	`stream`	struct, non-unit enum, unit-like enum	Exposes the underlying readwrite stream.
r	`temp`	field	Uses a field as a temporary variable. Only usable with the `binread` attribute macro.
r	`try`	field	Tries to parse and stores the `default` value for the type if parsing fails instead of returning an error.
rw	`try_calc`	field	Like `calc`, but returns a `Result`.
rw	`try_map`	all except unit variant	Like `map`, but returns a `Result`.
w	`write_with`	field	Specifies a custom function for writing a field.

Terminology

Each binrw attribute contains a comma-separated list of directives. The following terms are used when describing where particular directives are supported:

#[brw(…)]               // ← struct
struct NamedStruct {
    #[brw(…)]           // ← field
    field: Type
}

#[brw(…)]               // ← struct
struct TupleStruct(
    #[brw(…)]           // ← field
    Type,
);

#[brw(…)]               // ← struct
struct UnitStruct;

#[brw(…)]               // ← non-unit enum
enum NonUnitEnum {
    #[brw(…)]           // ← data variant
    StructDataVariant {
        #[brw(…)]       // ← field
        field: Type
    },

    #[brw(…)]           // ← data variant
    TupleDataVariant(
        #[brw(…)]       // ← field
        Type
    ),

    #[brw(…)]           // ← unit variant
    UnitVariant
}

#[brw(…)]               // ← unit-like enum
enum UnitLikeEnum {
    #[brw(…)]           // ← unit variant
    UnitVariantA,
    …
    #[brw(…)]           // ← unit variant
    UnitVariantN
}

Arguments

Arguments provide extra data necessary for readingwriting an object.

The import and args directives define the type of BinRead::Args BinWrite::Args and the values passed in the args argument of a BinRead::read_options BinWrite::write_options call, respectively.

Any (earlier only, when reading)earlier field or import can be referenced in args.

Ways to pass and receive arguments

There are 3 ways arguments can be passed and received:

Tuple-style arguments (or “ordered arguments”): arguments passed as a tuple
Named arguments: arguments passed as an object
Raw arguments: arguments passed as a type of your choice

Tuple-style arguments

Tuple-style arguments (or “ordered arguments”) are passed via args() and received via import():

#[br(import($($ident:ident : $ty:ty),* $(,)?))]
#[br(args($($value:expr),* $(,)?))]

#[bw(import($($ident:ident : $ty:ty),* $(,)?))]
#[bw(args($($value:expr),* $(,)?))]

This is the most common form of argument passing because it works mostly like a normal function call:

#[derive(BinRead)]
#[br(import(val1: u32, val2: &str))]
struct Child {
    // ...
}

#[derive(BinRead)]
struct Parent {
    val: u32,
    #[br(args(val + 3, "test"))]
    test: Child
}

#[derive(BinWrite)]
#[bw(import(val1: u32, val2: &str))]
struct Child {
    // ...
}

#[derive(BinWrite)]
struct Parent {
    val: u32,
    #[bw(args(val + 3, "test"))]
    test: Child
}

Named arguments

Named arguments are passed via args {} and received via import {} (note the curly braces), similar to a struct literal:

#[br(import { $($ident:ident : $ty:ty $(= $default:expr)?),* $(,)? })]
#[br(args { $($name:ident $(: $value:expr)?),* $(,)? } )]

#[bw(import { $($ident:ident : $ty:ty $(= $default:expr)?),* $(,)? })]
#[bw(args { $($name:ident $(: $value:expr)?),* $(,)? } )]

Field init shorthand and optional arguments are both supported.

Named arguments are particularly useful for container objects like Vec, but they can be used by any parserserialiser that would benefit from labelled, optional, or unordered arguments:

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

#[derive(BinWrite)]
#[bw(import {
    count: u32,
    other: u16 = 0 // ← optional argument
})]
struct Child {
    // ...
}

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

    #[bw(args {
        count: *count,
        other: 5
    })]
    test: Child,

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

When nesting named arguments, you can use the binrw::args! macro to construct the nested object:

#[derive(BinRead)]
#[br(import {
    more_extra_stuff: u32
})]
struct Inner {
    // ...
}

#[derive(BinRead)]
#[br(import {
    extra_stuff: u32,
    inner_stuff: <Inner as BinRead>::Args<'_>
})]
struct Middle {
    #[br(args_raw = inner_stuff)]
    inner: Inner
}

#[derive(BinRead)]
struct Outer {
    extra_stuff: u32,
    inner_extra_stuff: u32,

    #[br(args { // ← Middle::Args<'_>
        extra_stuff,
        inner_stuff: binrw::args! { // ← Inner::Args<'_>
            more_extra_stuff: inner_extra_stuff
        }
    })]
    middle: Middle,
}

#[derive(BinWrite)]
#[bw(import {
    more_extra_stuff: u32
})]
struct Inner {
    // ...
}

#[derive(BinWrite)]
#[bw(import {
    extra_stuff: u32,
    inner_stuff: <Inner as BinWrite>::Args<'_>
})]
struct Middle {
    #[bw(args_raw = inner_stuff)]
    inner: Inner
}

#[derive(BinWrite)]
struct Outer {
    extra_stuff: u32,
    inner_extra_stuff: u32,

    #[bw(args { // ← Middle::Args<'_>
        extra_stuff: *extra_stuff,
        inner_stuff: binrw::args! { // ← Inner::Args<'_>
            more_extra_stuff: *inner_extra_stuff
        }
    })]
    middle: Middle,
}

Named arguments can also be used with types that manually implement BinReadBinWrite by creating a separate type for its arguments that implements binrw::NamedArgs.

The count and offset directives are sugar for setting the count and offset arguments on any named arguments object; see those directives’ documentation for more information.

Raw arguments

Raw arguments allow the BinRead::Args BinWrite::Args type to be specified explicitly and to receive all arguments into a single variable:

#[br(import_raw($binding:ident : $ty:ty))]
#[br(args_raw($value:expr))] or #[br(args_raw = $value:expr)]

#[bw(import_raw($binding:ident : $ty:ty))]
#[bw(args_raw($value:expr))] or #[bw(args_raw = $value:expr)]

They are most useful for argument forwarding:

type Args = (u32, u16);

#[derive(BinRead)]
#[br(import_raw(args: Args))]
struct Child {
    // ...
}

#[derive(BinRead)]
#[br(import_raw(args: Args))]
struct Middle {
    #[br(args_raw = args)]
    test: Child,
}

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

    #[br(args(1, 2))]
    mid: Middle,

    // identical to `mid`
    #[br(args_raw = (1, 2))]
    mid2: Middle,
}

type Args = (u32, u16);

#[derive(BinWrite)]
#[bw(import_raw(args: Args))]
struct Child {
    // ...
}

#[derive(BinWrite)]
#[bw(import_raw(args: Args))]
struct Middle {
    #[bw(args_raw = args)]
    test: Child,
}

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

    #[bw(args(1, 2))]
    mid: Middle,

    // identical to `mid`
    #[bw(args_raw = (1, 2))]
    mid2: Middle,
}

The assert directive validates objects and fields after they are read or before they are written, after they are read, before they are written, returning an error if the assertion condition evaluates to false:

#[br(assert($cond:expr $(,)?))]
#[br(assert($cond:expr, $msg:literal $(,)?)]
#[br(assert($cond:expr, $fmt:literal, $($arg:expr),* $(,)?))]
#[br(assert($cond:expr, $err:expr $(,)?)]

#[bw(assert($cond:expr $(,)?))]
#[bw(assert($cond:expr, $msg:literal $(,)?)]
#[bw(assert($cond:expr, $fmt:literal, $($arg:expr),* $(,)?))]
#[bw(assert($cond:expr, $err:expr $(,)?)]

Multiple assertion directives can be used; they will be combined and executed in order.

Assertions added to the top of an enum will be checked against every variant in the enum.

Any (earlier only, when reading)earlier field or import can be referenced by expressions in the directive. When reading, anAn assert directive on a struct, non-unit enum, or data variant can access the constructed object using the self keyword.