Module binrw::attribute::write [−][src]
Expand description
Documentation of directives of the #[bw]
attribute
(This is currently in a WIP state and likely quite broken)
List of directives
Directive | Supports | Description |
---|---|---|
align_after | field | Aligns the writer to the Nth byte after writing data. |
align_before | field | Aligns the writer to the Nth byte before writing data. |
args | struct field, data variant | Passes arguments to another BinWrite type. |
args_raw | struct field, data variant | Like args , but specifies a type containing the arguments. |
assert | struct, field, non-unit enum, data variant | Asserts that a condition is true before writing. |
big | all except unit variant | Sets the byte order to big-endian. |
calc | field | Computes the value of a field instead of pulling the value from a struct. Removes the field from the actual type definition. |
ignore | field | Skip writing the field. |
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 | Writes a magic constant. |
map | all except unit variant | Maps a value before writing. When used in the top-level position, the map function must take Self . |
pad_after | field | Writes N bytes of padding after writing the field. |
pad_before | field | Writes N bytes of padding before writing the field. |
pad_size_to | field | Ensures the writer is at least N bytes after the starting position for this field. |
write_with | field | Specifies a custom function for writing a field. |
repr | unit-like enum | Specifies the underlying type for a unit-like (C-style) enum. |
restore_position | field | Restores the writer’s position after writing a field. |
seek_before | field | Moves the writer to a specific position before writing data. |
try_map | all except unit variant | Like map , but returns a BinResult . |
Padding and alignment
BinWrite offers different directives for common forms of data structure alignment.
The pad_before
and pad_after
directives skip a specific number of bytes
either before or after writing a field, respectively:
#[bw(pad_after = $skip_bytes:expr)] or #[bw(pad_after($skip_bytes:expr))]
#[bw(pad_before = $skip_bytes:expr)] or #[bw(pad_before($skip_bytes:expr))]
#[brw(pad_after = $skip_bytes:expr)] or #[brw(pad_after($skip_bytes:expr))]
#[brw(pad_before = $skip_bytes:expr)] or #[brw(pad_before($skip_bytes:expr))]
This is effectively equivelant to:
pos += padding;
The align_before
and align_after
directives align the next written byte to the
given byte alignment either before or after writing a field, respectively:
#[bw(align_after = $align_to:expr)] or #[bw(align_after($align_to:expr))]
#[bw(align_before = $align_to:expr)] or #[bw(align_before($align_to:expr))]
#[brw(align_after = $align_to:expr)] or #[brw(align_after($align_to:expr))]
#[brw(align_before = $align_to:expr)] or #[brw(align_before($align_to:expr))]
This is effectively equivelant to:
if pos % align != 0 {
pos += align - (pos % align);
}
Arguments
The import
and args
directives define the type of
BinWrite::Args
and the values passed in the args
argument of a BinWrite::write_options
call.
Any field or import can be referenced in #[bw(args)]
.
There are 3 types of arguments:
- Tuple-styled Arguments (Alternatively “Ordered Arguments”) - arguments passed as a tuple
- Named arguments - arguments passed as a builder that ensures all required arguments are
passed (can be manually constructed using
binrw::args
) - Raw arguments - the arguments are passed as a type of your choice
Examples
Tuple-styled arguments
Tuple-styled arguments are passed via args()
and recieved via import()
.
#[derive(BinWrite)]
#[bw(import(val1: u32, val2: &'static str))]
struct ImportTest {
// ...
}
#[derive(BinWrite)]
struct ArgsTets {
val: u32,
#[bw(args(val + 3, "test"))]
test: ImportTest
}
Named arguments
Named arguments are passed via args {}
and recieved via import {}
. (Note the curly braces)
#[derive(BinWrite)]
#[bw(import { count: u32, other: u16 = 0 })]
struct ImportTest {
// ...
}
#[derive(BinWrite)]
struct ArgsTets {
count: u32,
#[bw(args { count: *count, other: 5 })]
test: ImportTest,
#[bw(args { count: 3 })]
test2: ImportTest,
}
The syntax is designed to mimic Rust’s struct literal syntax. Another feature of named imports
is allowing to specify a default value in the form of name: type = value
, which makes
passing the argument optional.
Raw arguments
Raw arguments can be used to have a higher degree of control over the type of the arguments variable being passed into the writer.
#[derive(BinWrite)]
#[bw(import_raw(args: (u32, u16)))]
struct ImportTest {
// ...
}
#[derive(BinWrite)]
struct ArgsTets {
count: u32,
#[bw(args(1, 2))]
test: ImportTest,
// identical to the above
#[bw(args_raw = (1, 2))]
test2: ImportTest,
}
One common use of import_raw
and args_raw
is for easily forwarding arguments through to an
inner field of the structure.
Technical notes
The format for the import and args directives are as follows:
// tuple-styled args
#[bw(import($($ident:ident : $ty:ty),* $(,)?))]
#[bw(args($($value:expr),* $(,)?))]
// named args
#[bw(import{ $($ident:ident : $ty:ty $(= $default:expr)? ),* $(,)? })]
#[bw(args { $($name:ident $(: $value:expr)? ),* $(,)? } )]
// raw args
#[bw(import_raw( $binding:ident : $ty:ty ))]
#[bw(args_raw($value:expr))]
#[bw(args_raw = $value:expr)] // same as above, alternative syntax
A notable limitation of the arguments system is not allowing non-static lifetimes. This is due to the fact arguments desugar into approximately the following:
impl BinWrite for MyType {
type Args = $ty;
fn write_options(..., args: Self::Args) -> Result<(), binrw::Error> {
// ...
}
}
Which, due to the fact the associated type Args
cannot have a lifetime tied to the associated
function write_options
, the type is inexpressible without GATs.
Assert
The assert
directive validates objects and fields before they are written,
returning an error if the assertion condition evaluates to false
:
#[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 field or import can be referenced by expressions in the directive.
Examples
Formatted error
#[derive(Debug, PartialEq)]
struct NotSmallerError(u32, u32);
#[derive(BinWrite, Debug)]
#[bw(assert(some_val > some_smaller_val, "oops! {} <= {}", some_val, some_smaller_val))]
struct Test {
some_val: u32,
some_smaller_val: u32
}
let mut writer = Cursor::new(Vec::new());
let err = writer.write_be(&Test{ some_val: 1, some_smaller_val: 3 }).unwrap_err();
assert!(matches!(err.root_cause(), binrw::Error::AssertFail { .. }));
Custom error
#[derive(Debug, PartialEq)]
struct NotSmallerError(u32, u32);
impl core::fmt::Display for NotSmallerError {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
write!(f, "{} <= {}", self.0, self.1)
}
}
#[derive(BinWrite, Debug)]
#[bw(assert(some_val > some_smaller_val, NotSmallerError(*some_val, *some_smaller_val)))]
struct Test {
some_val: u32,
some_smaller_val: u32
}
let mut writer = Cursor::new(Vec::new());
let err = writer.write_be(&Test { some_val: 1, some_smaller_val: 3 }).unwrap_err();
assert_eq!(err.custom_err(), Some(&NotSmallerError(1, 3)));
Errors
If the assertion fails and there is no second argument, or a string literal
is given as the second argument, an AssertFail
error is returned.
If the assertion fails and an expression is given as the second argument,
a Custom
error containing the result of the
expression is returned.
Arguments other than the condition are not evaluated unless the assertion fails, so it is safe for them to contain expensive operations without impacting performance.
In all cases, the writer’s position is reset to where it was before parsing started.
Byte order
The big
and little
directives specify the byte order
of data in a struct, enum, variant, or field:
#[bw(big)]
#[bw(little)]
The is_big
and is_little
directives conditionally set the byte order of
a struct field:
#[bw(is_little = $cond:expr)] or #[bw(is_little($cond:expr))]
#[bw(is_big = $cond:expr)] or #[bw(is_big($cond:expr))]
The is_big
and is_little
directives are primarily useful when byte order
is defined in the data itself. Any 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 theWriteOptions
object passed toBinWrite::write_options
by the caller - The host machine’s native byte order
Caculations
The calc
directive computes the value of a field instead of writing the value
from the type itself.
#[bw(calc = $value:expr)] or #[bw(calc($value:expr))]
Any field (earlier or later) or import can be referenced by the expression in the directive.
Note: within BinWrite
calc removes the field from the struct, similarly to
#[bw(temp)]
. The field also needs to be marked #[bw(temp)]
in order to ensure
the writer does not try and store a value in the non-existent field.
Examples
A simple example showing how calc is necessary for writing an array prefixed by a count:
#[binwrite]
struct MyType {
#[bw(calc = items.len() as u32)]
size: u32,
items: Vec<u8>,
}
let mut writer = Cursor::new(Vec::new());
writer.write_be(&MyType { items: vec![0, 1, 2] }).unwrap();
And another example showing how #[bw(temp)]
is needed when making this round-trip:
#[binrw]
struct MyType {
#[br(temp)]
#[bw(calc = items.len() as u32)]
size: u32,
#[br(count = size)]
items: Vec<u8>,
}
let list: MyType = Cursor::new(b"\0\0\0\x03\0\x01\x02").read_be().unwrap();
let mut writer = Cursor::new(Vec::new());
writer.write_be(&list).unwrap();
Default
The default
directive, and its alias ignore
, sets the value of the field
to its Default
instead of dumping data from the
writer:
#[bw(default)] or #[bw(ignore)]
#[brw(default)] or #[brw(ignore)]
Examples
#[binrw]
#[bw(import { x: u32, _y: u8 })]
struct MyStruct {
#[br(temp, ignore)]
#[bw(calc = x)]
x_copy: u32,
}
let mut x = binrw::io::Cursor::new(Vec::new());
MyStruct {}
.write_options(&mut x, &Default::default(), binrw::args! { x: 3, _y: 2 })
.unwrap();
The magic
directive matches magic numbers
in data:
#[bw(magic = $magic:literal)] or #[bw(magic($magic:literal))]
The magic number can be a byte literal, byte string, char, float, or integer. When a magic number is matched, parsing begins with the first byte after the magic number in the data. When a magic number is not matched, an error is returned.
Examples
#[derive(BinWrite, Debug)]
#[bw(magic = b"TEST")]
struct Test {
val: u32
}
#[derive(BinWrite, Debug)]
#[bw(magic = 1.2f32)]
struct Version(u16);
#[derive(BinWrite)]
enum Command {
#[bw(magic = 0u8)] Nop,
#[bw(magic = 1u8)] Jump { loc: u32 },
#[bw(magic = 2u8)] Begin { var_count: u16, local_count: u16 }
}
Errors
If the specified magic number does not match the data, a
BadMagic
error is returned and the writer’s
position is reset to where it was before parsing started.
Map
The map
and try_map
directives allow data to be written using one type and
stored as another:
#[bw(map = $map_fn:expr)] or #[map($map_fn:expr))]
#[bw(try_map = $map_fn:expr)] or #[try_map($map_fn:expr))]
When using map
on a field, the map function must explicitly declare the
type of the data to be written in its first parameter and return a value which
matches the type of the field. The map function can be a plain function,
closure, or call expression which returns a plain function or closure.
When using try_map
on a field, the same rules apply, except that the
function must return a Result
instead.
When using map
or try_map
on a struct or enum, the map function must
return Self
or Result<Self, E>
.
Any field or import can be referenced by the expression in the directive.
Examples
Using map
on a field
#[derive(BinWrite)]
struct MyType {
#[bw(map = |x: &String| -> u8 { x.parse().unwrap() })]
int_str: String
}
let mut writer = Cursor::new(Vec::new());
writer.write_be(&MyType { int_str: "1".to_string() }).unwrap();
assert_eq!(&writer.into_inner()[..], b"\x01")
Using try_map
on a field
#[derive(BinWrite)]
struct MyType {
#[bw(try_map = |&x| -> BinResult<i8> { x.try_into().map_err(|_| todo!()) })]
value: u8
}
let mut writer = Cursor::new(Vec::new());
writer.write_be(&MyType { value: 3 });
assert_eq!(&writer.into_inner()[..], b"\x03")
Using map
on a struct to create a bit field
The modular-bitfield
crate can be used
along with map
to create a struct out of raw bits.
use modular_bitfield::prelude::*;
// The cursor dumps a single byte
#[bitfield]
#[derive(BinWrite, Clone, Copy)]
#[bw(map = |&x| Self::into_bytes(x))]
pub struct PackedData {
status: B4,
is_fast: bool,
is_static: bool,
is_alive: bool,
is_good: bool,
}
// example byte: 0x53
// [good] [alive] [static] [fast] [status]
// 0 1 0 1 0011
// false true false true 3
Errors
If the try_map
function returns a binrw::io::Error
or
a std::io::Error
, an Io
error is returned. For
any other error type, a Custom
error is returned.
In all cases, the writer’s position is reset to where it was before parsing started.
Repr
The repr
directive is used on a unit-like (C-style) enum to specify the
underlying type to use when reading the field and matching variants:
#[br(repr = $ty:ty)] or #[br(repr($ty:ty))]
#[brw(repr = $ty:ty)] or #[brw(repr($ty:ty))]
Examples
#[derive(BinWrite)]
#[bw(big, repr = i16)]
enum FileKind {
Unknown = -1,
Text,
Archive,
Document,
Picture,
}
Errors
If a read fails, an Io
error is returned. If no
variant matches, a NoVariantMatch
error
is returned.
In all cases, the writer’s position is reset to where it was before parsing started.
Restore Position
The restore_position
directive restores the position of the writer after
a field is writen:
#[bw(restore_position)]
To seek to an arbitrary position, use seek_before
.
Example
#[binwrite]
struct MyType {
#[bw(restore_position)]
my_u24: u32,
override_byte: u8,
}
let mut writer = Cursor::new(Vec::new());
writer.write_be(&MyType { my_u24: 3, override_byte: 1 }).unwrap();
assert_eq!(&writer.into_inner()[..], b"\x01\x00\x00\x03");
Here a u32 (my_u24) is written, then the first byte is overwritten by the byte “override_byte”.
Custom writers
The write_with
directive specifies a custom writing function that can be
used to override the default BinWrite
implementation for
a type, or to dump values which have no BinWrite
implementation at all:
#[bw(write_with = $write_fn:expr)] or #[bw(write_with($write_fn:expr))]
#[brw(write_with = $write_fn:expr)] or #[brw(write_with($write_fn:expr))]
Any field or import can be referenced by the expression in the directive (for example, to construct a writer function by passing a value to a function that returns a closure).
Examples
Using a custom writer
fn custom_writer<W: binrw::io::Write + binrw::io::Seek>(
&amount: &u16,
writer: &mut W,
_opts: &WriteOptions,
_: (),
) -> binrw::BinResult<()> {
for _ in 0..amount {
writer.write_all(b"abcd")?;
}
Ok(())
}
#[derive(BinWrite)]
struct MyData {
x: u8,
#[bw(write_with = custom_writer)]
y: u16,
}
fn dump_mydata() {
let mut x = Cursor::new(Vec::new());
MyData { x: 1, y: 2 }
.write_options(&mut x, &WriteOptions::new(Endian::Big), ())
.unwrap();
assert_eq!(&x.into_inner()[..], b"\x01abcdabcd");
}