NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
crates.io
crates.io, #2656 most downloaded on crates.io
Derive macro for binrw
Latest stable
0.15.2
Last release 4 months ago
23 Jul 2026
Ships fairly regularly
a new release about every 4 months
Some releases are documented
notes for 13 of 29 stable releases
Nothing withdrawn
no release was ever pulled
6 years old
30 releases · first in 2021
Drag across the ruler to compare, or tap a release to open it.
binrw is now future-compatible with pub_use_of_private_extern_crate. ( #361 . Thanks, @jakobhellermann !)
The rarely-used variadic signature for #[binrw::parser] and #[binrw::writer] helper functions now requires a field name (i.e. fn foo(...) must now be
#[binrw::parser] and #[binrw::writer] helper functions now requires a field name (i.e. fn foo(...) must now be fn foo(_: ...) so that the Rust compiler team can do good things. (#342)Your coding agent can read these notes before it upgrades. Set up the MCP server →
The generic parameter lists for binrw::helpers functions have been reordered to put most-frequently-used parameters first.
binrw::helpers functions have been reordered to put most-frequently-used parameters first.binrw::helpers functions to support borrowed arguments.magic will now return an Io(UnexpectedEof) error when all attempts to read magic result in an UnexpectedEof. Previously, this would return NoVariantMatch. (#324, #325. Thanks, @plaflamme!)PosValue now includes implementations for Default and BinWrite. The BinWrite implementation simply treats PosValue as a wrapper and writes the stored value in place; the pos field is ignored. Use the seek_before and (optionally) restore_position directives if you want to write a PosValue value to a different position in the output stream. (#270, #273. Thanks, @amirbou!)BinWrite::write_ne and BinWrite::write_ne_args convenience functions have been added to match the same functions in the BinRead API.SeekFrom::End with TakeSeek now correctly seeks relative to the end of the stream if the stream is shorter than the limit. (#291)binrw::helpers::count_with to return a Vec<{integer}> using a custom function will no longer ignore the custom function. (#318. Thanks, @kitlith!)binrw::helpers functions.args directive can now be used when closures are passed to parse_with or write_with.BinReadExt and BinWriteExt traits are now appropriately annotated with #[inline].Nothing published for this version
Passing a SeekFrom::End to TakeSeek::seek now correctly seeks from the end of the TakeSeek stream instead of the end of the inner stream.
SeekFrom::End to TakeSeek::seek now correctly seeks from the end of the TakeSeek stream instead of the end of the inner stream. (#291)In derived BinWrite implementations, imported variables are now exposed before field variables, to match the way lexical scoping normally works. If an
BinWrite implementations, imported variables are now exposed before field variables, to match the way lexical scoping normally works. If an import and a field have the same name, this will cause the import to be shadowed. Previously, the field would be shadowed.parse_with and map together in an incompatible way.BinWrite derives without triggering a type mismatch error.'_ within nested types inside an import directive. (#241)verbose-backtrace is enabled and a derived type contains a docblock with a completely empty line. (#263)clippy::unnecessary_fallible_conversions lints.Nothing published for this version
Using parse_with / write_with , map_stream , and args together will no longer raise an error about incompatible stream types.
parse_with/write_with, map_stream, and args together will no longer raise an error about incompatible stream types. (#240)Using parse_with with map/try_map will no longer raise an error about incompatible types when the types are actually compatible.
Using parse_with with map/try_map will no longer raise an error about incompatible types when the types are actually compatible. (#239)
Using stream directive together with map_stream no longer causes a borrowck error.
stream directive together with map_stream no longer causes a borrowck error. (#236)The stream specified by map_stream is now only used when reading the inner value(s) of the field/struct/enum it is applied to. Previously, the mapped
map_stream is now only used when reading the inner value(s) of the field/struct/enum it is applied to. Previously, the mapped stream would also be used for magic, padding, etc. when those directives were also applied to the same field or type, but this caused problems with re-borrowing the stream and made the scope of the directive confusing.map_stream with count without causing a borrowck error.parse_with function that is not Copy without causing a borrowck error. (#185)BinWrite on a type whose associated Args type implements Default but is not the unit type. (Thanks, @octylFractal!)PhantomData<T> with BinWrite where T is not BinWrite. (Thanks, @DCNick3! #230)custom_err on an error with a backtrace will now correctly return the original custom error. (#228)Error::custom_err will now always return the custom error even if there is a backtrace associated with it. (#228)self in top-level #[bw] directives now works as expected. (#232)#[bw(assert)] now actually emits assertions on enums and data enum variants instead of silently accepting the directive without emitting any code.Nothing published for this version
The default behaviour of FilePtr has been changed to always immediately seek to and read the pointed-to value. Helper functions have been added to the
FilePtr has been changed to always immediately seek to and read the pointed-to value. Helper functions have been added to the file_ptr module to support the common case of reading from an offset table. Additional helper functions and types will be added in future releases to improve support for file indirection.BinRead::after_parse API has been removed since it was rarely used, usually broken by manual BinRead implementations, and made it impossible to use borrowed values in arguments in some cases. For custom two-pass parsing, one alternative is to create an object that will store data that need to be used during the second pass, pass a mutable reference to that object as an argument to read_options, add data to that object during the first pass, then use the recorded data from the object to perform the required action for the second pass.deref_now, offset_after, and postprocess_now have been removed as they were designed to control the after_parse API which no longer exists. Any field with a deref_now or postprocess_now directive can simply remove the directive to achieve equivalent functionality. Any struct that used offset_after should reorder the fields so the dependent field is after the offset location.For more detail on these changes, see #210.
helpers module.this from an assert directive is no longer supported. Replace this with the supported self keyword instead.file_ptr module. These helpers can be combined with the seek_before directive to support both relative and absolute positioning of the pointed-to data. See the documentation for usage information and examples.assert directives on structs, non-unit enums, and data variants can now access the constructed object using the self keyword. (Thanks, @octylFractal!) (#219)Clone is no longer a required trait for arguments passed to parse_with functions. (Thanks, @octylFractal!)Clone is no longer a required trait for arguments passed to BinReaderExt methods.BinRead is no longer a required trait for dereferencing a value from FilePtr. (#218)map and try_map functions can now mutably borrow values.dbg now also prints information about any padding and alignment directives on a field.count directive no longer attempts useless conversions. (Thanks, @poliorcetics!) (#206)dbg now returns the correct position of a field when using pad_before or align_before. (#188)Nothing published for this version
# Bug fixes * #[binrw::parser] and #[binrw::writer] now correctly handle receiving a single argument (thanks, @octylFractal!) * #[br(count)] now retur
#[binrw::parser] and #[binrw::writer] now correctly handle receiving a single argument (thanks, @octylFractal!)#[br(count)] now returns an error if the given count is out of range instead of using unwrap and panicking (#194)Nothing published for this version
Enums variants using #[br(magic)] with mixed data types (i.e. enum Foo { #[br(magic(0_u8))] A, #[br(magic(1_i16))] B }) will now always parse top-to-b
#[br(magic)] with mixed data types (i.e. enum Foo { #[br(magic(0_u8))] A, #[br(magic(1_i16))] B }) will now always parse top-to-bottom. Previously, variants would be parsed in groups by type. To maximise performance when parsing enums with mixed magic types, make sure variants with the same magic data type are contiguous. (Thanks, @MrNbaYoh!)BinrwNamedArgs macro and trait have been renamed to NamedArgs.ReadOptions::offset field has been moved and is now a named argument specific to the FilePtr type. The #[br(offset)] and #[br(offset_after)] directives will continue to work without any change, but manual uses of FilePtr must now pass the offset in arguments instead of options.ReadOptions and WriteOptions have been removed and replaced with a single Endian parameter.Args associated type now takes a lifetime to support borrowed arguments. Custom helper functions that don’t need to support borrowed arguments can use the 'static lifetime to maintain the previous behaviour.#[br(dbg)] directive can be used for quick and dirty debugging output to stderr. (Thanks, @Swiftb0y!) (#50, #162)args_iter helper can be used for parsing any field where each item is parsed using a value from another iterator as an argument (e.g. an object containing a list of header entries, followed by a list of body entries, where each body entry requires data from the corresponding header entry to be parsed.)TakeSeek reader adapter is a seekable version of the std::io::Take adapter. Use it by importing the TakeSeekExt trait and calling take_seek on any Read + Seek stream.#[binrw::parser] and #[binrw::writer] attributes simplify the creation of functions compatible with the parse_with and write_with directives.#[brw(try_calc)] directive adds a fallible version of the existing calc directive.#[brw(map_stream)])verbose-backtrace crate feature (enabled by default). Disabling this feature removes extra decorations, ANSI codes, and source text from the built-in error formatting.Cursor now overrides Seek::stream_position for improved performance using that API.args directive is missing from a field that requires it. (#67, #76)#[binread] and #[binwrite] on a struct or enum is now equivalent to just using #[binrw]. Previously, this was an error.#[br(assert)] directives now cause clearer error messages that explicitly state that an assertion failed. Previously, only the expression that failed to assert was given in the output.Cursor now actually seeks when using SeekFrom::End.#[br(try)] now only constructs a default value when parsing actually fails.assert, count, offset, offset_after, and parse_with directives now point correctly at the source of the error.The read_bytes helper, deprecated since 0.2.0, has been removed. Use Vec directly.
The read_bytes helper, deprecated since 0.2.0, has been removed. Use Vec<u8> directly.
The NullString and NullWideString APIs have been rewritten to use only standard Rust traits:
| before 0.10 | as of 0.10 |
|---|---|
T::from_string(s) |
From<String> or From<&str> |
s.into_string() |
s.to_string() or Display trait |
s.into_string_lossless() |
TryFrom<T> for String trait |
Two BinWrite API functions have been renamed for consistency with the BinRead API:
| before 0.10 | as of 0.10 |
|---|---|
BinWrite::write_to(...) |
BinWrite::write(...) |
BinWrite::write_with_args(...) |
BinWrite::write_args(...) |
The HasMagic trait has been renamed to meta::ReadMagic.
The Endian::Native variant has been removed and replaced by an equivalent constant, Endian::NATIVE.
The Default implementation for Endian has been removed. Use an explicit value where needed instead.
Convenience functions that do not accept a byte order (e.g. BinRead::read(...), BinWrite::write(...)) are now only callable if the underlying type also implements meta::ReadEndian (for reads) and meta::WriteEndian (for writes). This prevents unintentional architecture-specific byte ordering. These new traits are automatically derived for types that specify a byte order and for built-in types that do not have any endianness (e.g. Vec<u8>).
BufReader wrapper significantly improves performance when reading from non-memory streams (#141)NoSeek wrapper enables reading and writing non-seekable streams (#6, #78)BinRead, BinWrite, and FilePtr (#134)binread, binrw, and binwrite attributes are now also part of the binrw preludeVec<u32>) (#129)if directive is now also supported in #[bw] attributes (#113, #146)Clonecount and args are incorrectly combined, or when passing the wrong type to args (#112)no_std implementations of the Read and Write traits to improve feature parity with the std implementationsDebug implementations of NullString and NullWideString no longer allocate memoryBinRead and BinWritetry_map = {closure} on a struct now generates valid codeargs directives now point to the correct location of the problemimpl BinWrite for Box<[u8]> is now actually selected by the compilerbinrw::args!NullString and WideNullString types are now correctly marked with EqBinWrite on unit structs no longer causes a panicpre_assert directives now correctly apply to unit enum valuesNothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
One column per quarter.