Macro bitfield

macro_rules! bitfield {
    {
        /* full syntax */

        ( // visibility qualifiers:
          custom:$vis_custom:vis,   // custom fields
          extra:$vis_extra:vis      // extra functionality
        )
        // $vis:  the visibility of the struct.
        // $name: the name of the new struct.
        // $T: the inner integer primitive type (u8, i32, …).
        $(#[$struct_attributes:meta])*
        $vis:vis struct $name:ident($T:ty) {
            // Custom fields (panics if $field_start > $field_end || field_end >= $T::BITS):
            // $field: the name of the field
            // $field_start: the starting bit index.
            // $field_end: the ending bit index (optional).
            $(
                $(#[$field_attrs:meta])*
                $field:ident: $field_start:expr, $field_end:expr; // NAME: from_bit, to_bit;
            )*
        }
    } => { ... };
    {
        /* optional syntax */

        (custom:$vis_custom:vis, extra:$vis_extra:vis $(,)?) // optional trailing comma
        $(#[$struct_attributes:meta])*
        $vis:vis struct $name:ident($T:ty) {
            $(
                $(#[$field_attrs:meta])*
                $field:ident: $field_start:expr $(,$field_end:expr)?; // NAME: bit;
            )*
        }
    } => { ... };
    { (custom) // only public custom fields
        $($tt:tt)+ } => { ... };
    { (extra) // only public extra methods
        $($tt:tt)+ } => { ... };
    { // everything public
        $($tt:tt)+ } => { ... };
}

Available on _bit·· only.

Creates a custom bit field struct.

The inner type must be an integer primitive.

The new struct already derives Clone, Copy, Debug, Default, PartialEq, Eq and Hash.

Features

This macro depends on enabling any of the _bit_* features. E.g. _bit_u8.

Examples

See also the bitfield example.

bitfield! {
    /// My custom bit field struct.
    struct MyBf(u8) {
        // single bit fields:
        FIRST_BIT: 0;
        SECOND_BIT: 1;
        THIRD_BIT: 2;
        // multi-bit fields:
        MASK1: 0, 2;
        MASK2: 3, 6;
    }
}
let b = MyBf::new_zeroed();
assert![b.is_empty()];

See also the enumset! macro.