Module binrw::attribute::read[−][src]

Expand description

A documentation-only module for directives used in the #[br] and #[binread] attributes.

List of directives

Directive	Supports	Description
`align_after`	field	Aligns the reader to the Nth byte after reading data.
`align_before`	field	Aligns the reader to the Nth byte before reading data.
`args`	struct field, data variant	Passes arguments to another `BinRead` object.
`args_raw`	struct field, data variant	Like `args`, but specifies a tuple containing the arguments.
`assert`	struct, field, non-unit enum, data variant	Asserts that a condition is true. Can be used multiple times.
`big`	all except unit variant	Sets the byte order to big-endian.
`calc`	field	Computes the value of a field instead of reading data.
`count`	field	Sets the length of a vector.
`default`	field	Uses the `default` value for a field instead of reading data.
`deref_now`	field	An alias for `postprocess_now`.
`err_context`	field	Add additional context to errors.
`if`	field	Reads data only if a condition is true.
`ignore`	field	An alias for `default`.
`import`	struct, non-unit enum, unit-like enum	Defines extra arguments for a struct or enum.
`import_tuple`	struct, non-unit enum, unit-like enum	Like `import`, but receives the arguments as a tuple.
`is_big`	field	Conditionally sets the byte order to big-endian.
`is_little`	field	Conditionally set the byte order to little-endian.
`little`	all except unit variant	Sets the byte order to little-endian.
`magic`	all	Matches a magic number.
`map`	all except unit variant	Maps a read value to a new value. When used on a struct or enum, the map function must return `Self`.
`offset`	field	Modifies the offset used by a `FilePtr`.
`pad_after`	field	Skips N bytes after reading a field.
`pad_before`	field	Skips N bytes before reading a field.
`pad_size_to`	field	Ensures the reader is at least N bytes after the starting position for this field.
`parse_with`	field	Specifies a custom function for reading a field.
`postprocess_now`	field	Calls `after_parse` immediately after reading data instead of after all fields have been read.
`pre_assert`	struct, non-unit enum, unit variant	Like `assert`, but checks the condition before parsing.
`repr`	unit-like enum	Specifies the underlying type for a unit-like (C-style) enum.
`restore_position`	field	Restores the reader’s position after reading a field.
`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.
`return_unexpected_error`	non-unit enum	Returns a single generic error on failure.
`seek_before`	field	Moves the reader to a specific position before reading data.
`temp`	field	Uses a field as a temporary variable. Only usable with the `binread` attribute macro.
`try`	field	Tries to parse and stores the `default` value for the type if parsing fails instead of returning an error.
`try_map`	all except unit variant	Like `map`, but returns a `BinResult`.

Byte order

The big and little directives specify the byte order of data in a struct, enum, variant, or field:

#[br(big)]
#[br(little)]

The is_big and is_little directives conditionally set the byte order of a struct field:

#[br(is_little = $cond:expr)] or #[br(is_little($cond:expr))]
#[br(is_big = $cond:expr)] or #[br(is_big($cond:expr))]

The is_big and is_little directives are primarily useful when byte order is defined in the data itself. Any earlier field or import can be referenced in the condition. Conditional byte order directives can only be used on struct fields.

The order of precedence (from highest to lowest) for determining byte order within an object is:

A directive on a field
A directive on an enum variant
A directive on the struct or enum
The endian property of the ReadOptions object passed to BinRead::read_options by the caller
The host machine’s native byte order

However, if a byte order directive is added to a struct or enum, that byte order will always be used, even if the object is embedded in another object or explicitly called with a different byte order:

#[derive(BinRead, Debug, PartialEq)]
#[br(little)] // ← this *forces* the struct to be little-endian
struct Child(u32);

#[derive(BinRead, Debug)]
struct Parent {
    #[br(big)] // ← this will be ignored
    child: Child,
};

let mut options = ReadOptions::new(Endian::Big /* ← this will be ignored */);
Child::read_options(&mut Cursor::new(b"\x01\0\0\0"), &options, ())

When manually implementing BinRead::read_options or a custom parser function, the byte order is accessible from ReadOptions::endian.