bitflag_attr/

lib.rs

//! Bitflag-attr is a library for Rust that allows to generate types for C-style bitflags with
//! ergonomic APIs using attribute macros and enums.
//!
//! # Overview
//!
//! The primary item of this crate is the [`bitflag`] macro. This attribute macro allows to define a
//! flags type from a Rust C-style enum definition, turning it into a struct with the flags as
//! associated constants.
//!
//! The remainder of this documentation is organized as follows:
//!
//! - [Features](#features) gives a very brief summary of the features `bitflag-attr` does and does not
//!   support.
//! - [Usage](#usage) shows how to add `bitflag-attr` to your Rust project.
//! - [Formatting and parsing](#formatting-and-parsing) documents the human-readable format used to
//!   parse form and format into strings
//! - [Specification and Terminology](#specification-and-terminology) documents about the
//!   specification and the terminology used by this crate.
//! - [Crate features](#crate-features) documents the Cargo features that can be enabled or disabled
//!   for this crate.
//!
//! Also, these sub-modules serve to provide longer form documentation:
//!
//! - [Changelog](crate::changelog)
//! - [Specification and Terminology](crate::spec)
//! - [Example of a generated code by the `bitflag` macro](crate::example_generated)
//!
//! # Features
//!
//! Here is a non-exhaustive list of the things that `bitflag-attr` supports:
//!
//! - Ergonomically create a flags type from native C-like enum syntax
//! - `no_std` support with opt-in options to use `alloc` and `std`
//! - Generate ergonomic API for the generated flags type
//! - Generated methods are almost entirely const-compatible
//! - Generated flags type auto-implements several convenient traits (complete list in the
//!   [`bitflag`] documentation)
//! - Generated [`fmt::Debug`] implementation outputs human-readable, binary, octal and hexadecimal
//!   representation of the flags value for better debugging inspection.
//! - Support to the enum syntax for deriving [`Default`] by using `#[default]` to choose the
//!   default flags value
//! - Support to use all integer types and type alias in `core` and `std` as well as most common
//!   integer type alias of `libc` with opt-in option to use [other type alias as well as custom
//!   type alias](#code-generation-features)
//! - Opt-in support for generating `serde::Serialize` and `serde::Deserialize` by using the `serde`
//!   [crate feature]
//! - Opt-in support for generating `arbitrary::Arbitrary` by using the `arbitrary` [crate feature]
//! - Opt-in support for generating `bytemuck::Zeroable` and `bytemuck::Pod` by using the `bytemuck`
//!   [crate feature]
//!
//! # Usage
//!
//! The `bitflag-attr` project is [on crates.io](https://crates.io/crates/bitflag-attr) and can be
//! used by adding `bitflag-attr` to your dependencies in your project's `Cargo.toml`.
//! Or more simply, by using `cargo add`.
//!
//! ```sh
//! cargo add bitflag-attr
//! ```
//!
//! or
//!
//! ```toml
//! [dependencies]
//! bitflag-attr = "0.11.1"
//! ```
//!
//! ## Generating flags type
//!
//! Use the [`bitflag`] attribute macro to generate flags types:
//!
//! ```rust
//! use bitflag_attr::bitflag;
//!
//! #[bitflag(u32)]
//! #[derive(Clone, Copy)]
//! enum Flags {
//!     A = 0b00000001,
//!     B = 0b00000010,
//!     C = 0b00000100,
//! }
//! ```
//!
//! Deriving [`Clone`] and [`Copy`] for the type is mandatory.
//!
//! The generated type is a **struct** wrapping the chosen primitive type.
//!
//! See the docs for the [`bitflag`] macro for the full syntax.
//!
//! Also see the [`example_generated`] module for an example of what the [`bitflag`] macro generates
//! for a flags type.
//!
//! ### Externally defined flags
//!
//! If you're generating flags types for an external source, such as a C API, you can use the
//! `non_exhaustive` attribute to communicate to the bitflags macro that there may be more valid
//! flags than the known flags.
//!
//! Without extra configuration, it defaults to `!0` (all bits set) as a mask of all bits the
//! external source may ever set, i.e. all bits are considered as possible values.
//!
//! ```rust
//! use bitflag_attr::bitflag;
//!
//! #[bitflag(u32)]
//! #[non_exhaustive] // All bits are considered as possible values.
//! #[derive(Debug, Clone, Copy)]
//! 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,
//! }
//! ```
//!
//! But you can also configure this value by using the helper attribute `reserved_bits` with a
//! desired value of valid bits that the external source may ever set.
//!
//! ```rust
//! use bitflag_attr::bitflag;
//!
//! #[bitflag(u32)]
//! #[non_exhaustive] // Communicate there is more potential valid flags than the known flags
//! #[reserved_bits = 0b001001111] // Specify the extra bits to take into consideration.
//! #[derive(Debug, Clone, Copy)]
//! 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,
//! }
//! ```
//!
//! Why should you do this? Generated methods like `all` and truncating operators like `!` only
//! consider bits in defined flags. Adding an unnamed flag makes those methods consider additional
//! bits, without generating additional constants for them. It helps compatibility when the external
//! source may start setting additional bits at any time. The
//! [known and unknown bits](#known-and-unknown-bits) section has more details on this behavior.
//!
//! ### Custom derives
//!
//! You can derive some traits on generated flags types if you enable Cargo features. The following
//! libraries are currently supported:
//!
//! - `serde`: Support `#[derive(Serialize, Deserialize)]`, using text for human-readable formats,
//!   and a raw number for binary formats.
//! - `arbitrary`: Support `#[derive(Arbitrary)]`, only generating flags values with known bits.
//! - `bytemuck`: Support `#[derive(Pod, Zeroable)]`, for casting between flags values and their
//!   underlying bits values.
//!
//! ### Adding custom methods
//!
//! The [`bitflag`] macro supports any attributes on generated flags types within the macro itself,
//! while `impl` blocks can be added normally:
//!
//! ```rust
//! # use bitflag_attr::bitflag;
//! #
//! #[bitflag(u32)]
//! // Attributes can be applied to flags types
//! #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
//! enum Flags {
//!     A = 0b00000001,
//!     B = 0b00000010,
//!     C = 0b00000100,
//! }
//!
//! // Impl blocks can be added to flags types normally
//! impl Flags {
//!     pub fn as_u64(&self) -> u64 {
//!         self.bits() as u64
//!     }
//! }
//! ```
//!
//! ## Working with flags values
//!
//! Use generated constants and standard bitwise operators to interact with flags values:
//!
//! ```rust
//! # use bitflag_attr::bitflag;
//! # #[bitflag(u32)]
//! # #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
//! # enum Flags {
//! #     A = 0b00000001,
//! #     B = 0b00000010,
//! #     C = 0b00000100,
//! # }
//! #
//! // union
//! let ab = Flags::A | Flags::B;
//!
//! // intersection
//! let a = ab & Flags::A;
//!
//! // difference
//! let b = ab - Flags::A;
//!
//! // complement
//! let c = !ab;
//! ```
//!
//! See the docs for the [`example_generated`] module and the [`Flags`] trait for more details on
//! operators and how they behave.
//!
//! # Formatting and parsing
//!
//! `bitflag-attr` defines a text format that can be used to convert any flags value to and from
//! strings.
//!
//! See the [`parser`] module for more details.
//!
//! # Specification and Terminology
//!
//! The terminology and behavior of generated flags types is specified in the documentation module
//! [`spec`]. Details are repeated in these docs where appropriate, but is exhaustively listed in
//! the spec. Some things are worth calling out explicitly here.
//!
//! ## Flags types, flags values, flags
//!
//! Some terminology to refer to things in the bitflags domain:
//!
//! - **Bits type**: A type that defines a fixed number of bits at specific locations.
//! - **Flag**: A set of bits in a bits type that may have a unique name.
//! - **Flags type**: A set of defined flags over a specific bits type.
//! - **Flags value**: An instance of a flags type using its specific bits value for storage.
//!
//! ```rust
//! # use bitflag_attr::bitflag;
//! #
//! #[bitflag(u8)]
//! //        -- Bits type
//! #[derive(Clone, Copy)]
//! enum FlagsType {
//! //   --------- Flags type
//!     A = 1,
//! //  ----- Flag
//! }
//!
//! let flag = FlagsType::A;
//! //  ---- Flags value
//! ```
//!
//! ## Known and unknown bits
//!
//! Any bits in a flag you define are called _known bits_. Any other bits are _unknown bits_. In the
//! following flags type:
//!
//! ```rust
//! # use bitflag_attr::bitflag;
//! #[bitflag(u8)]
//! #[derive(Clone, Copy)]
//! enum Flags {
//!     A = 1,
//!     B = 1 << 1,
//!     C = 1 << 2,
//! }
//! ```
//!
//! The known bits are `0b0000_0111` and the unknown bits are `0b1111_1000`.
//!
//! `bitflag_attr` doesn't guarantee that a flags value will only ever have known bits set, but some
//! operators will unset any unknown bits they encounter.
//!
//! If you're using `bitflags` for flags types defined externally, such as from C, you probably want
//! all bits to be considered known, in case that external source changes. You can do this using an
//! unnamed flag, as described in [externally defined flags](#externally-defined-flags).
//!
//! ## Zero-bit flags
//!
//! Flags with no bits set, in general, should be avoided because they interact strangely with
//! [`contains`] and [`intersects`]. A zero-bit flag is always contained, but is never intersected. The
//! names of zero-bit flags can be parsed, but are never formatted.
//!
//! [`contains`]: Flags::contains
//! [`intersects`]: Flags::intersects
//!
//! ## Multi-bit flags
//!
//! Flags that set multiple bits should be avoided unless each bit is also in a single-bit flag.
//! Take the following flags type as an example:
//!
//! ```rust
//! # use bitflag_attr::bitflag;
//! #[bitflag(u8)]
//! #[derive(Clone, Copy)]
//! enum Flags {
//!     A = 1,
//!     B = 1 | (1 << 1),
//! }
//! ```
//!
//! The result of `Flags::A ^ Flags::B` is `0b0000_0010`, which doesn't correspond to either
//! `Flags::A` or `Flags::B` even though it's still a known bit.
//!
//! [`example_generated`]: crate::example_generated::ExampleFlags
//!
//! # Crate Features
//!
//! ## Ecosystem features
//!
//! - **std** — When enabled, `bitflag-attr` will depend on the `std` crate. Currently no
//!   particular usage and, for all intents and purposes, the same as the `alloc` feature.
//! - **alloc** — When enabled, `bitflag-attr` will depend on the `alloc` crate. In particular,
//!   this enables functionality that requires or greatly benefits from dynamic memory allocation.
//!   If you can enable this, it is strongly encouraged that you do so. Without it, [parsing errors]
//!   will contain less information for error reporting.
//!
//! [parsing errors]: crate::parser::ParseError
//!
//! ## Code generation features
//!
//! - **serde** — When enabled, the [`bitflag`] macro will handle specially the `Serialize` and
//!   `Deserialize` traits passed to the enum's derive list and generate a custom implementation of
//!   those traits taking into account the human-readable format for the generated flags type.
//!   Without it, if these traits are listed in the derive list, they are passed forward to the
//!   generated code, i.e. the default derive will be used. This feature does **not** add the
//!   `serde` crate to your dependency tree, so your project must have it as a direct
//!   dependency.
//! - **arbitrary** — When enabled, the [`bitflag`] macro will handle specially the `Arbitrary` and
//!   trait passed to the enum's derive list and generate a custom implementation of this trait
//!   taking into account the known and unknown bits, erroring out on the later. Without it, if this
//!   trait are listed in the derive list, they are passed forward to the generated code, i.e. the
//!   default derive will be used. This feature does **not** add the `arbitrary` crate to your
//!   dependency tree, so your project must have it as a direct dependency.
//! - **bytemuck** — When enabled, the [`bitflag`] macro will handle specially the `Zeroable` and
//!   `Pod` traits passed to the enum's derive list and generate a custom implementation of
//!   those traits with static checks to ensure the correct marking. Without it, if these traits are
//!   listed in the derive list, they are passed forward to the generated code, i.e. the default
//!   derive will be used. This feature does **not** add the `bytemuck` crate to your dependency
//!   tree, so your project must have it as a direct dependency.
//! - **custom-types** — When enabled, the [`bitflag`] macro will allow the usage of types as
//!   parameters that are not in the list of [allowed types] at the cost of worse error messages if
//!   the used type does not satisfy the requirements for the usage.
//! - **const-mut-ref** — When enabled, the [`bitflag`] macro will generate as `const-fn` all
//!   generated methods that takes the flags value as mutable pointer. This is only allowed after
//!   Rust 1.83.0, and enabling this feature with versions inferior to this number will cause
//!   compilation errors. But if you satisfy this version limitation, it is strongly encouraged that
//!   you do enable it.
//!
//! [allowed types]: crate::bitflag#custom-types-feature
//! [crate feature]: #crate-features
#![no_std]

#[cfg(feature = "alloc")]
extern crate alloc;

#[cfg(any(test, feature = "std"))]
extern crate std;

use core::{
    fmt,
    ops::{BitAnd, BitAndAssign, BitOr, BitOrAssign, BitXor, BitXorAssign, Not},
};

pub use bitflags_attr_macros::bitflag;

pub mod iter;
pub mod parser;

/// Primitive types that can be used with [`bitflag`] attribute implement this trait.
pub trait BitsPrimitive:
    private::Sealed
    + Copy
    + PartialEq
    + BitAnd<Output = Self>
    + BitOr<Output = Self>
    + BitXor<Output = Self>
    + Not<Output = Self>
    + BitAndAssign
    + BitOrAssign
    + BitXorAssign
    + fmt::Binary
    + fmt::LowerHex
    + fmt::UpperHex
    + fmt::Octal
    + Sized
    + 'static
{
    /// A value with all bits unset.
    const EMPTY: Self;

    /// A value with all bits set.
    const ALL: Self;
}

mod private {
    pub trait Sealed {}
}

macro_rules! impl_primitive {
    ($($ty:ty),+ $(,)?) => {
        $(
            impl $crate::private::Sealed for $ty {}
            impl $crate::BitsPrimitive for $ty {
                const EMPTY: Self = 0;
                const ALL: Self = !0;
            }
            impl $crate::parser::ParseHex for $ty {
                #[inline]
                fn parse_hex(input: &str) -> Result<Self, $crate::parser::ParseError>
                where
                    Self: Sized
                {
                    <$ty>::from_str_radix(input, 16).map_err(|_| $crate::parser::ParseError::invalid_hex_flag(input))
                }
            }
        )+
    };
}

impl_primitive!(i8, i16, i32, i64, i128, isize);
impl_primitive!(u8, u16, u32, u64, u128, usize);

/// A set of defined flags using a bits type as storage.
///
/// ## Implementing `Flags`
///
/// This trait is implemented by the [`bitflag`] macro:
///
/// ```
/// use bitflag_attr::bitflag;
///
/// #[bitflag(u8)]
/// #[derive(Clone, Copy)]
/// enum MyFlags {
///   A = 1,
///   B = 1 << 1,
/// }
/// ```
///
/// It can also be implemented manually:
///
/// ```
/// use bitflag_attr::{Flags};
///
/// #[derive(Clone, Copy)]
/// struct MyFlags(u8);
///
/// impl Flags for MyFlags {
///     const NAMED_FLAGS: &'static [(&'static str, Self)] = &[
///         ("A", MyFlags(1)),
///         ("B", MyFlags(1 << 1)),
///     ];
///
///     const RESERVED_BITS: Self::Bits = 1 | (1 << 1);
///
///     type Bits = u8;
///
///     fn from_bits_retain(bits: Self::Bits) -> Self {
///         MyFlags(bits)
///     }
///
///     fn bits(&self) -> Self::Bits {
///         self.0
///     }
/// }
/// ```
///
/// ## Using `Flags`
///
/// The `Flags` trait can be used generically to work with any flags types. In this example,
/// we can count the number of defined named flags:
///
/// ```
/// # use bitflag_attr::{bitflag, Flags};
/// fn defined_flags<F: Flags>() -> usize {
///     F::NAMED_FLAGS.iter().count()
/// }
///
/// #[bitflag(u8)]
/// #[non_exhaustive]
/// #[derive(Clone, Copy)]
/// enum MyFlags {
///     A = 1,
///     B = 1 << 1,
///     C = 1 << 2,
/// }
///
/// assert_eq!(3, defined_flags::<MyFlags>());
/// ```
pub trait Flags: Sized + Copy + 'static {
    /// The set of named defined flags.
    const NAMED_FLAGS: &'static [(&'static str, Self)];

    /// All reserved bits values for the flags.
    ///
    /// The bits defined here can be named or unnamed and the values defined here will be considered
    /// for the [`all`] method as a known value.
    ///
    /// This can be used for [externally defined flags](crate#externally-defined-flags) or even
    /// reserving bits for future usage.
    ///
    /// Usually, the value of this constant can be either `0` or the bitor-ed bits values of the
    /// named flags[^1]. For externally defined flags, the most common value is `!0`, i.e. all bits.
    ///
    /// [^1]: By pure logic, all bits from named flags are reserved bits. But alternatively,
    /// "reserved bits" can be thought as only the extra bits to be reserved as known. For that
    /// reason, the default implementation of the [`all`] method consider this value **and** the
    /// values of [`NAMED_FLAGS`] to generate the resulting value.
    ///
    /// [`all`]: Flags::all
    /// [`NAMED_FLAGS`]: Flags::NAMED_FLAGS
    const RESERVED_BITS: Self::Bits;

    /// The underlying bits type.
    type Bits: BitsPrimitive;

    /// Return the underlying bits value.
    ///
    /// The returned value is exactly the bits set in this flags value.
    fn bits(&self) -> Self::Bits;

    /// Convert from `bits` value exactly.
    fn from_bits_retain(bits: Self::Bits) -> Self;

    /// Converts from a `bits` value. Returning [`None`] is any unknown bits are set.
    #[inline]
    fn from_bits(bits: Self::Bits) -> Option<Self> {
        let truncated = Self::from_bits_truncate(bits);

        if truncated.bits() == bits {
            Some(truncated)
        } else {
            None
        }
    }

    /// Convert from `bits` value, unsetting any unknown bits.
    #[inline]
    fn from_bits_truncate(bits: Self::Bits) -> Self {
        Self::from_bits_retain(bits & Self::all().bits())
    }

    /// Convert from a flag `name`.
    #[inline]
    fn from_flag_name(name: &str) -> Option<Self> {
        // Don't parse empty names as empty flags
        if name.is_empty() {
            return None;
        }

        Self::NAMED_FLAGS
            .iter()
            .find(|(s, _)| *s == name)
            .map(|(_, v)| Self::from_bits_retain(v.bits()))
    }

    /// Get a flags value with the bits of a flag with the given name set.
    ///
    /// This method will return `None` if `name` is empty or doesn't
    /// correspond to any named flag.
    #[inline]
    fn from_name(name: &str) -> Option<Self> {
        // Don't parse empty names as empty flags
        if name.is_empty() {
            return None;
        }

        for (flag_name, flag) in Self::NAMED_FLAGS {
            if *flag_name == name {
                return Some(Self::from_bits_retain(flag.bits()));
            }
        }

        None
    }

    /// Construct a flags value with all bits unset.
    #[inline]
    fn empty() -> Self {
        Self::from_bits_retain(Self::Bits::EMPTY)
    }

    /// Returns `true` if the flags value has all bits unset.
    #[inline]
    fn is_empty(&self) -> bool {
        self.bits() == Self::Bits::EMPTY
    }

    /// Returns a flags value that contains all value.
    ///
    /// This will include bits that do not have any flags/meaning.
    /// Use [`all`](Flags::all) if you want only the specified flags set.
    #[inline]
    fn all_bits() -> Self {
        Self::from_bits_retain(Self::Bits::ALL)
    }

    /// Returns `true` if the bitflag contains all value bits set.
    ///
    /// This will check for all bits.
    /// Use [`is_all`](Flags::is_all) if you want to check for all specified flags.
    #[inline]
    fn is_all_bits(&self) -> bool {
        self.bits() == Self::Bits::ALL
    }

    /// Construct a flags value with all known flags set.
    ///
    /// This will only set the flags specified as associated constant and the defined extra valid
    /// bits.
    #[inline]
    fn all() -> Self {
        let mut truncated = Self::Bits::EMPTY;

        for (_, flag) in Self::NAMED_FLAGS.iter() {
            truncated |= flag.bits();
        }

        truncated |= Self::RESERVED_BITS;

        Self::from_bits_retain(truncated)
    }

    /// Whether all known bits in this flags value are set.
    #[inline]
    fn is_all(&self) -> bool {
        // NOTE: We check against `Self::all` here, not `Self::Bits::ALL`
        // because the set of all flags may not use all bits
        Self::all().bits() | self.bits() == self.bits()
    }

    /// Construct a flags value with all known named flags set.
    ///
    /// This will only set the flags specified as associated constant **without** the defined
    /// extra valid bits.
    #[inline]
    fn all_named() -> Self {
        let mut truncated = Self::Bits::EMPTY;

        for (_, flag) in Self::NAMED_FLAGS.iter() {
            truncated |= flag.bits();
        }

        Self::from_bits_retain(truncated)
    }

    /// Returns `true` if the flags value contais all known named flags.
    #[inline]
    fn is_all_named(&self) -> bool {
        Self::all_named().bits() | self.bits() == self.bits()
    }

    /// Returns `true` if there are any unknown bits set in the flags value.
    #[inline]
    fn contains_unknown_bits(&self) -> bool {
        Self::all().bits() & self.bits() != self.bits()
    }

    /// Returns `true` if there are any unnamed known bits set in the flags value.
    #[inline]
    fn contains_unnamed_bits(&self) -> bool {
        Self::all_named().bits() & self.bits() != self.bits()
    }

    /// Returns a flags value with unknown bits removed from the original flags value.
    #[inline]
    fn truncated(&self) -> Self {
        Self::from_bits_retain(self.bits() & Self::all().bits())
    }

    /// Returns `true` if this flags value intersects with any value in `other`.
    ///
    /// This is equivalent to `(self & other) != Self::empty()`
    #[inline]
    fn intersects(&self, other: Self) -> bool
    where
        Self: Sized,
    {
        self.bits() & other.bits() != Self::Bits::EMPTY
    }

    /// Returns `true` if this flags value contains all values of `other`.
    ///
    /// This is equivalent to `(self & other) == other`
    #[inline]
    fn contains(&self, other: Self) -> bool
    where
        Self: Sized,
    {
        self.bits() & other.bits() == other.bits()
    }

    /// Remove any unknown bits from the flags.
    #[inline]
    fn truncate(&mut self)
    where
        Self: Sized,
    {
        *self = Self::from_bits_truncate(self.bits());
    }

    /// Returns the intersection from this flags value with `other`.
    #[must_use]
    #[inline]
    #[doc(alias = "and")]
    fn intersection(self, other: Self) -> Self {
        Self::from_bits_retain(self.bits() & other.bits())
    }

    /// Returns the union from this flags value with `other`.
    #[must_use]
    #[inline]
    #[doc(alias = "or")]
    fn union(self, other: Self) -> Self {
        Self::from_bits_retain(self.bits() | other.bits())
    }

    /// Returns the difference from this flags value with `other`.
    ///
    /// In other words, returns the intersection of this value with the negation of `other`.
    ///
    /// This method is not equivalent to `self & !other` when `other` has unknown bits set.
    /// `difference` won't truncate `other`, but the `!` operator will.
    #[must_use]
    #[inline]
    fn difference(self, other: Self) -> Self {
        Self::from_bits_retain(self.bits() & !other.bits())
    }

    /// Returns the symmetric difference from this flags value with `other`..
    #[must_use]
    #[inline]
    #[doc(alias = "xor")]
    fn symmetric_difference(self, other: Self) -> Self {
        Self::from_bits_retain(self.bits() ^ other.bits())
    }

    /// Returns the complement of the flags value.
    ///
    /// This is very similar to the `not` operation, but truncates non used bits.
    #[must_use]
    #[inline]
    #[doc(alias = "not")]
    fn complement(self) -> Self {
        Self::from_bits_truncate(!self.bits())
    }

    /// Set the flags in `other` in the value.
    #[inline]
    #[doc(alias = "insert")]
    fn set(&mut self, other: Self)
    where
        Self: Sized,
    {
        *self = Self::from_bits_retain(self.bits()).union(other);
    }

    /// Unset the flags bits in `other` in the value.
    ///
    /// This method is not equivalent to `self & !other` when `other` has unknown bits set.
    /// `remove` won't truncate `other`, but the `!` operator will.
    #[inline]
    #[doc(alias = "remove")]
    fn unset(&mut self, other: Self)
    where
        Self: Sized,
    {
        *self = Self::from_bits_retain(self.bits()).difference(other);
    }

    /// Toggle the flags in `other` in the value.
    #[inline]
    fn toggle(&mut self, other: Self)
    where
        Self: Sized,
    {
        *self = Self::from_bits_retain(self.bits()).symmetric_difference(other);
    }

    /// Resets the flags value to a empty state.
    #[inline]
    fn clear(&mut self) {
        *self = Self::empty()
    }

    /// Yield a set of contained flags values.
    ///
    /// Each yielded flags value will correspond to a defined named flag. Any unknown bits
    /// will be yielded together as a final flags value.
    #[inline]
    fn iter(&self) -> iter::Iter<Self> {
        iter::Iter::new(self)
    }

    /// Yield a set of contained named flags values.
    ///
    /// This method is like [`Flags::iter`], except only yields bits in contained named flags.
    /// Any unknown bits, or bits not corresponding to a contained flag will not be yielded.
    #[inline]
    fn iter_names(&self) -> iter::IterNames<Self> {
        iter::IterNames::new(self)
    }
}

///////////////////////////////////////////////////////////////////////////////
// Adapted from bitflags `bitflags_match!`
///////////////////////////////////////////////////////////////////////////////

/// A macro that matches flags values, similar to Rust's `match` statement.
///
/// In a regular `match` statement, the syntax `Flag::A | Flag::B` is interpreted as an or-pattern,
/// instead of the bitwise-or of `Flag::A` and `Flag::B`. This can be surprising when combined with flags types
/// because `Flag::A | Flag::B` won't match the pattern `Flag::A | Flag::B`. This macro is an alternative to
/// `match` for flags values that doesn't have this issue.
///
/// # Syntax
///
/// ```ignore
/// bitflag_match!(expression, {
///     pattern1 => result1,
///     pattern2 => result2,
///     ..
///     _ => default_result,
/// })
/// ```
///
/// The final `_ => default_result` arm is required, otherwise the macro will fail to compile.
///
/// # Examples
///
/// ```rust
/// use bitflag_attr::{bitflag, bitflag_match};
///
/// #[bitflag(u8)]
/// #[derive(Clone, Copy, PartialEq)]
/// enum Flags {
///     A = 1 << 0,
///     B = 1 << 1,
///     C = 1 << 2,
/// }
///
/// let flags = Flags::A | Flags::B;
///
/// bitflag_match!(flags, {
///     Flags::A | Flags::B => println!("A and/or B are set"),
///     _ => println!("neither A nor B are set"),
/// })
/// ```
///
/// # How it works
///
/// The macro expands to a series of `if` statements, checking equality between the input expression
/// and each pattern. This allows for correct matching of bitflag combinations, which is not possible
/// with a regular match expression due to the way bitflags are implemented.
///
/// Patterns are evaluated in order.
#[macro_export]
macro_rules! bitflag_match {
    ($operation:expr, {
        $($t:tt)*
    }) => {
        // Expand to a closure so we can use `return`
        // This makes it possible to apply attributes to the "match arms"
        (|| {
            $crate::__bitflag_match!($operation, { $($t)* })
        })()
    };
}

/// Expand the `bitflags_match` macro
#[macro_export]
#[doc(hidden)]
macro_rules! __bitflag_match {
    // Eat an optional `,` following a block match arm
    ($operation:expr, { $pattern:expr => { $($body:tt)* } , $($t:tt)+ }) => {
        $crate::__bitflag_match!($operation, { $pattern => { $($body)* } $($t)+ })
    };
    // Expand a block match arm `A => { .. }`
    ($operation:expr, { $pattern:expr => { $($body:tt)* } $($t:tt)+ }) => {
        {
            if $operation == $pattern {
                return {
                    $($body)*
                };
            }

            $crate::__bitflag_match!($operation, { $($t)+ })
        }
    };
    // Expand an expression match arm `A => x,`
    ($operation:expr, { $pattern:expr => $body:expr , $($t:tt)+ }) => {
        {
            if $operation == $pattern {
                return $body;
            }

            $crate::__bitflag_match!($operation, { $($t)+ })
        }
    };
    // Expand the default case
    ($operation:expr, { _ => $default:expr $(,)? }) => {
        $default
    }
}

/// A documentation module for this crate changelog.
///
/// This module is only available in the crate documentation.
#[cfg(doc)]
#[doc = include_str!("../CHANGELOG.md")]
#[allow(rustdoc::broken_intra_doc_links)]
pub mod changelog {}

/// A documentation module for in depth specification definition and terminology.
///
/// This module is only available in the crate documentation.
#[cfg(doc)]
#[cfg(not(doctest))]
#[doc = include_str!("../spec.md")]
pub mod spec {}

#[cfg(doc)]
pub mod example_generated;