macro_rules! bitfield {
    (
        $(#[$doc:meta])*
        $( [$( $derive:ident ),*] )?
        $( ($access:vis) )? $name:ident
        $(#[$flag_doc:meta])*
        $flag:ident u8 {
            $(
                $(#[$member_doc:meta])*
                $idx:literal : $field:ident
            )*
        }
    ) => { ... };
    (
        $(#[$doc:meta])*
         $( [$( $derive:ident ),*] )?
        $( ($access:vis) )? $name:ident
        $(#[$flag_doc:meta])*
        $flag:ident u16 {
            $(
                $(#[$member_doc:meta])*
                $idx:literal : $field:ident
            )*
        }
    ) => { ... };
    (
        $(#[$doc:meta])*
         $( [$( $derive:ident ),*] )?
        $( ($access:vis) )? $name:ident
        $(#[$flag_doc:meta])*
        $flag:ident u32 {
            $(
                $(#[$member_doc:meta])*
                $idx:literal : $field:ident
            )*
        }
    ) => { ... };
    (
        $(#[$doc:meta])*
         $( [$( $derive:ident ),*] )?
        $( ($access:vis) )? $name:ident
        $(#[$flag_doc:meta])*
        $flag:ident u64 {
            $( $(#[$member_doc:meta])* $idx:literal : $field:ident )*
        }
    ) => { ... };
    (
        $(#[$doc:meta])*
         $( [$( $derive:ident ),*] )?
        $( ($access:vis) )? $name:ident
        $(#[$flag_doc:meta])*
        $flag:ident u128 {
            $(
                $(#[$member_doc:meta])*
                $idx:literal : $field:ident
            )*
        }
    ) => { ... };
    (
        $(#[$doc:meta])*
         $( [$( $derive:ident ),*] )?
        $( ($access:vis) )? $name:ident
        $(#[$flag_doc:meta])*
        $flag:ident usize {
            $(
                $(#[$member_doc:meta])*
                $idx:literal : $field:ident
            )*
        }
    ) => { ... };
}
Expand description

Generates a bitfield struct and a corresponding flag enum.

Can be used multiple times in a single codebase as long as the identifiers are unique or are isolated so as not to clash.

See the crate::example module for an example of the generated output.

Args

  • (pub) - optional accessor: if provided, both generated items will public. If omitted, both will be private.

  • ExampleField - name for the generated bitfield struct. (results in struct ExampleField(...))

  • ExampleFlags - name for the generated flag enum. (results in enum ExampleFlags { ... })

  • u8 - unsigned integer type to use as a bit array. Must be an unsigned integer
    valid options are: u8,u16, u32, u64, u128, usize

  • 0 : Flag0 - defines each member of the flag enum.
    The left hand side must be a u8 (0..=254) and must be less than the number of bits in the underlying unsigned type. This value determines the index of the target bit within the field.
    The right hand side can be any valid identifier (unique to this enum). These identifiers will be used to access the corresponding field.

Examples:

Full Example - (see below for explanation for each parameter):

use ubits::bitfield;

    bitfield! {
        /// Optional docstring
        /// for [`ExampleField`] struct
        (pub) ExampleField
        /// Optional docstring
        /// for [`ExampleFlags`] enum
        ExampleFlags u8 {
            /// Optional docstring for [`ExampleFlags::Flag0`]
            0 : Flag0
            /// Optional docstring for [`ExampleFlags::Flag1`]
            1 : Flag1
            /// Optional docstring for [`ExampleFlags::Flag2`]
            2 : Flag2
            /// Optional docstring for [`ExampleFlags::Flag3`]
            3 : Flag3
            /// Optional docstring for [`ExampleFlags::Flag4`]
            4 : Flag4
            /// Optional docstring for [`ExampleFlags::Flag5`]
            5 : Flag5
            /// Optional docstring for [`ExampleFlags::Flag6`]
            6 : Flag6
            /// Optional docstring for [`ExampleFlags::Flag7`]
            7 : Flag7
        }
    }

You don’t have to name all the fields if you don’t need them…

You can use just a few from the front:

use ubits::bitfield;

    bitfield! {
        /// Optional docstring
        /// for [`ExampleField`] struct
        (pub) ExampleField
        /// Optional docstring
        /// for [`ExampleFlags`] enum
        ExampleFlags u8 {
            /// Optional docstring for [`ExampleFlags::Flag0`]
            0 : Flag0
            /// Optional docstring for [`ExampleFlags::Flag1`]
            1 : Flag1
            /// Optional docstring for [`ExampleFlags::Flag2`]
            2 : Flag2
        }
    }

… or any valid indices:

use ubits::bitfield;

    bitfield! {
        /// Optional docstring
        /// for [`ExampleField`] struct
        (pub) ExampleField
        /// Optional docstring
        /// for [`ExampleFlags`] enum
        ExampleFlags u8 {
            /// Optional docstring for [`ExampleFlags::Flag0`]
            0 : Flag0
            /// Optional docstring for [`ExampleFlags::Flag1`]
            3 : Flag1
            /// Optional docstring for [`ExampleFlags::Flag2`]
            6 : Flag2
        }
    }