Trait binwrite::BinWrite

pub trait BinWrite {
    fn write_options<W: Write>(
        &self, 
        writer: &mut W, 
        options: &WriterOption
    ) -> Result<()>;

    fn write<W: Write>(&self, writer: &mut W) -> Result<()> { ... }
}

A trait providing the ability to write the struct to a writer

Derive-based example:

use binwrite::BinWrite;

#[derive(BinWrite)]
struct Point {
    x: i32,
    y: i32,
}

fn main() {
    let point = Point { x: 1, y: -2 };
    let mut bytes = vec![];

    point.write(&mut bytes).unwrap();

    assert_eq!(bytes, vec![1, 0, 0, 0, 0xFE, 0xFF, 0xFF, 0xFF]);
}

Setting Endianness

use binwrite::BinWrite;

#[derive(BinWrite)]
#[binwrite(big)]
struct Foo {
    bar: u32,
    bar2: i32,

    #[binwrite(little)]
    bar3: u32,
}

fn main() {
    let point = Foo {
        bar: 1,
        bar2: -2,
        bar3: 3
    };
    let mut bytes = vec![];

    point.write(&mut bytes).unwrap();

    assert_eq!(bytes, vec![0, 0, 0, 1, 0xFF, 0xFF, 0xFF, 0xFE, 3, 0, 0, 0]);
}

Using a preprocessor

use binwrite::BinWrite;

#[derive(BinWrite)]
struct Foo {
    #[binwrite(preprocessor(u32_to_hex_string))]
    bar: u32,
    bar2: String,
}

fn u32_to_hex_string(var: u32) -> String {
    format!("{:X}", var)
}

fn main() {
    let point = Foo {
        bar: 0xF00D,
        bar2: String::from(" looks like food")
    };
    let mut bytes = vec![];

    point.write(&mut bytes).unwrap();

    assert_eq!(bytes, b"F00D looks like food");
}

Using a custom writer

For more complicated or more reusable serialization methods, you may want to use a custom writer instead of just preprocessing.

use std::io::{Write, Result};
use binwrite::{BinWrite, WriterOption};

#[derive(BinWrite)]
struct Foo {
    vec_without_len: Vec<u8>,
    #[binwrite(with(write_vec_with_len), big)]
    vec_with_len: Vec<u8>,
}

pub fn write_vec_with_len<W, T>(vec: &Vec<T>, writer: &mut W, options: &WriterOption) -> Result<()>
    where W: Write,
             T: BinWrite,
{
    BinWrite::write_options(&(vec.len() as u32), writer, options)?;
    BinWrite::write_options(vec, writer, options)
}

fn main() {
    let point = Foo {
        vec_without_len: vec![0, 1, 2, 3],
        vec_with_len: vec![0, 1, 2, 3],
    };
    let mut bytes = vec![];

    point.write(&mut bytes).unwrap();

    assert_eq!(bytes, vec![0, 1, 2, 3, 0, 0, 0, 4, 0, 1, 2, 3]);
}

Built in Writers:

Currently supported built in writers:

• cstr - "C string" (null terminated string)
• utf16 - UTF-16/2 byte wide/Windows string, endianness is used to determine byte order
• utf16_null - same as utf16 but with a null terminator
• ignore - skip writing this field

use binwrite::BinWrite;

#[derive(BinWrite)]
struct Foo {
    #[binwrite(cstr)]
    bar: u32,
    #[binwrite(cstr)]
    bar2: String,
    #[binwrite(ignore)]
    bar3: u8,
}

fn main() {
    let point = Foo {
        bar: 1234,
        bar2: String::from("this is null terminated"),
        bar3: 0xFF
    };
    let mut bytes = vec![];

    point.write(&mut bytes).unwrap();

    assert_eq!(bytes, b"1234\0this is null terminated\0");
}

Padding/Alignment

binwrite also has the ability to align to the nearest X bytes

use binwrite::BinWrite;

#[derive(BinWrite)]
struct Foo {
    // For tuples/arrays/vecs/slices of types implementing BinWrite work out of the box
    // and items will just be written in order.
    bar: [char; 3],
    // pad specifies the padding before
    // pad_after specifiers the padding after
    #[binwrite(align(8), align_after(0x10))]
    bar2: String,
}

fn main() {
    let point = Foo {
        bar: ['a', 'b', 'c'],
        bar2: String::from("test string")
    };
    let mut bytes = vec![];

    point.write(&mut bytes).unwrap();

    assert_eq!(bytes, b"abc\0\0\0\0\0test string\0\0\0\0\0\0\0\0\0\0\0\0\0");
}

use pad and pad_after for fixed amounts of padding.

Advanced Preprocessors

Using generics/closures, you can make "configurable" and more reusable preprocessors.

Example (a configurable "add X before writing"):

use binwrite::BinWrite;

fn add<T: std::ops::Add<Output = T> + Copy>(lhs: T) -> impl Fn(T) -> T {
    move |rhs| lhs + rhs
}

#[derive(BinWrite)]
struct Foo {
    #[binwrite(preprocessor(add(10)))]
    bar_u32: u32,
    #[binwrite(preprocessor(add(-1)))]
    bar_i64: i64,
}

fn main() {
    let mut bytes = vec![];

    Foo {
        bar_u32: 2,
        bar_i64: 0,
    }.write(&mut bytes).unwrap();

    assert_eq!(bytes, vec![0xCu8, 0, 0, 0, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF]);
}

Postprocessors

Postprocessors are functions which take a Vec<u8> (what would normally be written) and produce any type that implements BinWrite, which is then written in place of the bytes.

use binwrite::BinWrite;

fn not_crc32(bytes: &Vec<u8>) -> u32 {
    4
}

fn prepend_crc32(bytes: Vec<u8>) -> (u32, Vec<u8>) {
    (
        not_crc32(&bytes),
        bytes
    )
}

#[derive(BinWrite)]
#[binwrite(big)]
struct Foo {
    #[binwrite(postprocessor(prepend_crc32))]
    bar: u32,
}

fn main() {
    let mut bytes = vec![];

    Foo {
        bar: 2,
    }.write(&mut bytes).unwrap();

    assert_eq!(bytes, vec![0x0u8, 0, 0, 4, 0, 0, 0, 0x2]);
}

Required methods

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

Loading content...

Provided methods

fn write<W: Write>(&self, writer: &mut W) -> Result<()>

Loading content...

Implementations on Foreign Types

impl BinWrite for char

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    _options: &WriterOption
) -> Result<()>

impl BinWrite for u8

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    _options: &WriterOption
) -> Result<()>

impl BinWrite for i8

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    _options: &WriterOption
) -> Result<()>

impl BinWrite for u16

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl BinWrite for u32

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl BinWrite for u64

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl BinWrite for i16

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl BinWrite for i32

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl BinWrite for i64

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl BinWrite for f32

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl BinWrite for f64

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<B: BinWrite> BinWrite for Vec<B>

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<B: BinWrite> BinWrite for [B]

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<B: BinWrite> BinWrite for [B; 0]

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<B: BinWrite> BinWrite for [B; 1]

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<B: BinWrite> BinWrite for [B; 2]

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<B: BinWrite> BinWrite for [B; 3]

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<B: BinWrite> BinWrite for [B; 4]

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<B: BinWrite> BinWrite for [B; 5]

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<B: BinWrite> BinWrite for [B; 6]

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<B: BinWrite> BinWrite for [B; 7]

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<B: BinWrite> BinWrite for [B; 8]

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<B: BinWrite> BinWrite for [B; 9]

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<B: BinWrite> BinWrite for [B; 10]

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<B: BinWrite> BinWrite for [B; 11]

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<B: BinWrite> BinWrite for [B; 12]

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<B: BinWrite> BinWrite for [B; 13]

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<B: BinWrite> BinWrite for [B; 14]

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<B: BinWrite> BinWrite for [B; 15]

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<B: BinWrite> BinWrite for [B; 16]

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<B: BinWrite> BinWrite for [B; 17]

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<B: BinWrite> BinWrite for [B; 18]

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<B: BinWrite> BinWrite for [B; 19]

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<B: BinWrite> BinWrite for [B; 20]

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<'_> BinWrite for &'_ [u8]

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    _options: &WriterOption
) -> Result<()>

impl BinWrite for str

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    _options: &WriterOption
) -> Result<()>

impl<'_> BinWrite for &'_ str

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    _options: &WriterOption
) -> Result<()>

impl<'_, B: BinWrite> BinWrite for &'_ B

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl BinWrite for String

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<b1: BinWrite, b2: BinWrite, b3: BinWrite, b4: BinWrite, b5: BinWrite, b6: BinWrite, b7: BinWrite, b8: BinWrite, b9: BinWrite, b10: BinWrite, b11: BinWrite, b12: BinWrite, b13: BinWrite, b14: BinWrite, b15: BinWrite, b16: BinWrite, b17: BinWrite, b18: BinWrite, b19: BinWrite, b20: BinWrite> BinWrite for (b1, b2, b3, b4, b5, b6, b7, b8, b9, b10, b11, b12, b13, b14, b15, b16, b17, b18, b19, b20)

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<b2: BinWrite, b3: BinWrite, b4: BinWrite, b5: BinWrite, b6: BinWrite, b7: BinWrite, b8: BinWrite, b9: BinWrite, b10: BinWrite, b11: BinWrite, b12: BinWrite, b13: BinWrite, b14: BinWrite, b15: BinWrite, b16: BinWrite, b17: BinWrite, b18: BinWrite, b19: BinWrite, b20: BinWrite> BinWrite for (b2, b3, b4, b5, b6, b7, b8, b9, b10, b11, b12, b13, b14, b15, b16, b17, b18, b19, b20)

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<b3: BinWrite, b4: BinWrite, b5: BinWrite, b6: BinWrite, b7: BinWrite, b8: BinWrite, b9: BinWrite, b10: BinWrite, b11: BinWrite, b12: BinWrite, b13: BinWrite, b14: BinWrite, b15: BinWrite, b16: BinWrite, b17: BinWrite, b18: BinWrite, b19: BinWrite, b20: BinWrite> BinWrite for (b3, b4, b5, b6, b7, b8, b9, b10, b11, b12, b13, b14, b15, b16, b17, b18, b19, b20)

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<b4: BinWrite, b5: BinWrite, b6: BinWrite, b7: BinWrite, b8: BinWrite, b9: BinWrite, b10: BinWrite, b11: BinWrite, b12: BinWrite, b13: BinWrite, b14: BinWrite, b15: BinWrite, b16: BinWrite, b17: BinWrite, b18: BinWrite, b19: BinWrite, b20: BinWrite> BinWrite for (b4, b5, b6, b7, b8, b9, b10, b11, b12, b13, b14, b15, b16, b17, b18, b19, b20)

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<b5: BinWrite, b6: BinWrite, b7: BinWrite, b8: BinWrite, b9: BinWrite, b10: BinWrite, b11: BinWrite, b12: BinWrite, b13: BinWrite, b14: BinWrite, b15: BinWrite, b16: BinWrite, b17: BinWrite, b18: BinWrite, b19: BinWrite, b20: BinWrite> BinWrite for (b5, b6, b7, b8, b9, b10, b11, b12, b13, b14, b15, b16, b17, b18, b19, b20)

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<b6: BinWrite, b7: BinWrite, b8: BinWrite, b9: BinWrite, b10: BinWrite, b11: BinWrite, b12: BinWrite, b13: BinWrite, b14: BinWrite, b15: BinWrite, b16: BinWrite, b17: BinWrite, b18: BinWrite, b19: BinWrite, b20: BinWrite> BinWrite for (b6, b7, b8, b9, b10, b11, b12, b13, b14, b15, b16, b17, b18, b19, b20)

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<b7: BinWrite, b8: BinWrite, b9: BinWrite, b10: BinWrite, b11: BinWrite, b12: BinWrite, b13: BinWrite, b14: BinWrite, b15: BinWrite, b16: BinWrite, b17: BinWrite, b18: BinWrite, b19: BinWrite, b20: BinWrite> BinWrite for (b7, b8, b9, b10, b11, b12, b13, b14, b15, b16, b17, b18, b19, b20)

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<b8: BinWrite, b9: BinWrite, b10: BinWrite, b11: BinWrite, b12: BinWrite, b13: BinWrite, b14: BinWrite, b15: BinWrite, b16: BinWrite, b17: BinWrite, b18: BinWrite, b19: BinWrite, b20: BinWrite> BinWrite for (b8, b9, b10, b11, b12, b13, b14, b15, b16, b17, b18, b19, b20)

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<b9: BinWrite, b10: BinWrite, b11: BinWrite, b12: BinWrite, b13: BinWrite, b14: BinWrite, b15: BinWrite, b16: BinWrite, b17: BinWrite, b18: BinWrite, b19: BinWrite, b20: BinWrite> BinWrite for (b9, b10, b11, b12, b13, b14, b15, b16, b17, b18, b19, b20)

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<b10: BinWrite, b11: BinWrite, b12: BinWrite, b13: BinWrite, b14: BinWrite, b15: BinWrite, b16: BinWrite, b17: BinWrite, b18: BinWrite, b19: BinWrite, b20: BinWrite> BinWrite for (b10, b11, b12, b13, b14, b15, b16, b17, b18, b19, b20)

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<b11: BinWrite, b12: BinWrite, b13: BinWrite, b14: BinWrite, b15: BinWrite, b16: BinWrite, b17: BinWrite, b18: BinWrite, b19: BinWrite, b20: BinWrite> BinWrite for (b11, b12, b13, b14, b15, b16, b17, b18, b19, b20)

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<b12: BinWrite, b13: BinWrite, b14: BinWrite, b15: BinWrite, b16: BinWrite, b17: BinWrite, b18: BinWrite, b19: BinWrite, b20: BinWrite> BinWrite for (b12, b13, b14, b15, b16, b17, b18, b19, b20)

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<b13: BinWrite, b14: BinWrite, b15: BinWrite, b16: BinWrite, b17: BinWrite, b18: BinWrite, b19: BinWrite, b20: BinWrite> BinWrite for (b13, b14, b15, b16, b17, b18, b19, b20)

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<b14: BinWrite, b15: BinWrite, b16: BinWrite, b17: BinWrite, b18: BinWrite, b19: BinWrite, b20: BinWrite> BinWrite for (b14, b15, b16, b17, b18, b19, b20)

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<b15: BinWrite, b16: BinWrite, b17: BinWrite, b18: BinWrite, b19: BinWrite, b20: BinWrite> BinWrite for (b15, b16, b17, b18, b19, b20)

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<b16: BinWrite, b17: BinWrite, b18: BinWrite, b19: BinWrite, b20: BinWrite> BinWrite for (b16, b17, b18, b19, b20)

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<b17: BinWrite, b18: BinWrite, b19: BinWrite, b20: BinWrite> BinWrite for (b17, b18, b19, b20)

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<b18: BinWrite, b19: BinWrite, b20: BinWrite> BinWrite for (b18, b19, b20)

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<b19: BinWrite, b20: BinWrite> BinWrite for (b19, b20)

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl<b20: BinWrite> BinWrite for (b20,)

fn write_options<W: Write>(
    &self,
    writer: &mut W,
    options: &WriterOption
) -> Result<()>

impl BinWrite for ()

fn write_options<W: Write>(&self, _: &mut W, _: &WriterOption) -> Result<()>

Loading content...

Implementors

Loading content...