ninox.rs-bitfields

A small create, ment to help working with bitfields / bitflags in rust.

License

This project is licensed under AGPL-3.0-or-later. For more informations see the LICENSE file inside the repository here, or alternative online under https://www.gnu.org/licenses/.

What are bitfields/-flags?

While normal datastructures are strictly aligned bytewise, bitfields and -flags are aligned bitwise. This means that they span individual bit's instead of full bytes.

Bitfields are your typical structured type, as it has fields that can cover one or more bits; Bitflags on the other hand are more a set of different flags are each represented by a single bit.

Usage

Bitflags

use ninox_bitfields::*;

struct MyFlags(u8);

#[bitflags(
    // How the value of an variant should be interpret;
    // The default is `()`.
    value = (
        fill      // Non-declared values are auto-filled
        | is_bitpos // Value is considered to be a bit position instead of a mask
    ),

    // The "container" type, I.e. which type holds the bits:
    //  - `Self` means to rewrite the annotated type to a tuple-struct
    //      that holds bits. Variants are rewritten to associated constants.
    //  - `use X` will use the specified type "X" as the container.
    //      An example would be `struct X(u32)`.
    //  - `gen X` will generate the container type under the name "X".
    container = use MyFlags,

    // Which implementations to generate;
    // defaults to (bit_ops, bool_ops, from_repr, into_repr):
    //  - all: all supported (see below)
    //  - fmt: formatting core::fmt::{Binary, LowerHex, UpperHex, Octal}
    //  - bit_ops: bit operations (including operators via core::ops)
    //  - bool_ops: `.has()` method
    //  - from_repr: representation type -> container
    //  - into_repr: container -> representation type
    //  - debug: implements `core::fmt::Debug` for the container
    //  - display: implements `core::fmt::Display` for the container
    impl = all,

    // Options:
    //   - bitand_is_has: the bitwise and operation `&` / `.and()` will yield an `bool`
    //        as it will function as an `.has()` instead of an full bitwise operation.
    opts = (bitand_is_has),
)]
#[repr(u32)]
enum MyFlag {
    A = 0,
    B = 1,
    C = 2,
}

fn main() {
    let flags = MyFlag::A & MyFlag::B;
    if flags & MyFlag::A {
        println!("A ist set!");
    }
}

Roadmap

• implement the gen X and Self values for the container option
• implement the value option
• add more documentation to the traits
• expand the BitflagOps trait
• refactor some more operations into traits
• implement actual bitfields instead of just bitflags
• maybe split the bitflags macro attrubute into two, one for the enum, one for the container when using use X