Attribute Macro bitflag

#[bitflag]

An attribute macro that transforms an C-like enum into a bitflag struct implementing an type API similar to the bitflags crate, and implementing traits as listed below.

The attribute requires that the [Clone] and [Copy] traits are derived for the type.

Generated trait implementations

This macro generates some trait implementations: ops:Not, ops:BitAnd, ops:BitOr, ops:BitXor, ops:BitAndAssign, ops:BitOrAssign, ops:BitXorAssign, fmt::Binary, fmt::LowerHex, fmt::UpperHex, fmt::Octal, From, [Extend], [FromIterator], [IntoIterator]

The custom fmt::Debug implementation will only be generated if it is included in the #[derive(...)] parameters.

Serde feature

If the crate is compiled with the serde feature, this crate will generate implementations for the serde::{Serialize, Deserialize} traits if they are included in the #[derive(...)] parameters, but it will not import/re-export these traits, your project must have serde as dependency.

Having this feature enabled will also generate a type to represent the parsing error and helper functions to do parsing the generated type from strings. And will generate the implementation for the FromStr trait.

Custom types

If the crate is compiled with the custom-types feature, it allows to use more than the types defined in Rust core (i8,u8,i16,u16,i32,u32,i64,u64,i128,u128,isize, usize,c_char,c_schar,c_uchar,c_short,c_ushort,c_int,c_uint,c_long,c_ulong, c_longlong,c_ulonglong) as long as it is a type alias to one of those types.

The reason it is behind a feature flag is that to ensure the validity of such constrain, we have to pay the price of having much worse error messages. With this feature enabled, a invalid type will cause a massive wall of error message.

Example

use bitflag_attr::bitflag;

#[bitflag(u32)]
#[derive(Debug, Clone, Copy, PartialEq, PartialOrd, Eq, Ord, Hash)]
pub enum Flags {
    /// The value `A`, at bit position `0`.
    A = 0b00000001,
    /// The value `B`, at bit position `1`.
    B = 0b00000010,
    /// The value `C`, at bit position `2`.
    C = 0b00000100,

    /// The combination of `A`, `B`, and `C`.
    ABC = A | B | C,
}

Without generating fmt::Debug:

use bitflag_attr::bitflag;

#[bitflag(u32)]
#[derive(Clone, Copy, PartialEq, PartialOrd, Eq, Ord, Hash)]
pub enum Flags {
    /// The value `A`, at bit position `0`.
    A = 0b00000001,
    /// The value `B`, at bit position `1`.
    B = 0b00000010,
    /// The value `C`, at bit position `2`.
    C = 0b00000100,

    /// The combination of `A`, `B`, and `C`.
    ABC = A | B | C,
}

Syntax

#[bitflag($ty)]
$visibility enum $StructName {
    FlagOne = flag1_value_expr,
    FlagTwo = flag2_value_expr,
    // ...
    FlagN = flagn_value_expr,
}