bitfield-derive

This crate provides derive to generate struct with bitfield access.

Examples

use bitfield_derive::BitFields;

#[derive(Default, BitFields)]
struct Foo {
    #[bitfield(bar @ "3:0" as u8 "The bar flags")]
    #[bitfield(baz @ "7:4" as u8 "The baz flags")]
    #[bitfield(ro, _ @ "8" as bool)] // Read only
    #[bitfield(_ , set_wr @ "9" as bool)] // Write only
    #[bitfield(stuff @ "31:16" as u16)]
    #[bitfield(all_bits @ "31:0")]
    _bi1: u32,
    other: usize,
}

// Instance a struct with bitfields.
let mut foo = Foo::default();

// Initial states.
assert_eq!(foo.bar(), 0);
assert_eq!(foo.baz(), 0);

foo.set_bar(7);
foo.set_baz(3);
assert_eq!(foo.bar(), 7);
assert_eq!(foo.baz(), 3);

// Overflowing tests.
foo.set_bar(0x13);
foo.set_baz(0x17);
assert_eq!(foo.bar(), 3);
assert_eq!(foo.baz(), 7);

foo.set_bar(0x0f);
foo.set_baz(0x0f);
assert_eq!(foo.bar(), 0x0f);
assert_eq!(foo.baz(), 0x0f);

assert_eq!(foo.ro(), false);
// Compile fail if uncomment the follow line.
// foo.set_ro(false);

// Compile fail if uncomment the follow line.
// assert_eq!(foo.wr(), 0);
foo.set_wr(true);

assert_eq!(foo.stuff(), 0);
foo.set_stuff(0xffff);
assert_eq!(foo.stuff(), 0xffff);

// All bits in the container field.
assert_eq!(foo.all_bits(), 0xffff_02ff);
foo.set_all_bits(0);
assert_eq!(foo.all_bits(), 0);

Visibility

The visibility of the bitfield follows the container field.

Examples:

use bitfield_derive::BitFields;

#[derive(Default, BitFields)]
pub struct Foo {
    #[bitfield(bar @ "3:0" as u8 "The bar flags")]
    pub _bi1: u32;
    #[bitfield(baz @ "3:0" as u8 "The baz flags")]
    _bi2: u32;
}

The container field Foo::_bi1 is pub, so the Foo::bar() and Foo::set_bar() are implements as:

impl Foo {
    pub fn bar(&self) -> u8 { ... }
    pub fn set_bar(&mut self, value: u8) { ... }
}

The container field Foo::_bi2 is private, so the Foo::baz() and Foo::set_baz() are implements as:

impl Foo {
    fn baz(&self) -> u8 { ... }
    fn set_baz(&mut self, value: u8) { ... }
}

Documentation

The last parameter of the bitfield is the description of the getter and setter.

The document generated by the above example is as follows:

[-] pub(crate) fn bar(&self) -> u8
    The bar flags

[-] pub(crate) fn set_bar(&mut self, value: u8)
    See also: bar

[-] pub(crate) fn baz(&self) -> u8
    The baz flags

[-] pub(crate) fn set_baz(&mut self, value: u8)
    See also: baz

...