Crate bitflags_lite 

The bitflags-lite crate provides a lightweight, generic bitflags implementation for Rust.

BitFlags<T, U> is a #[repr(transparent)] wrapper around an integer T that adds a compile-time tag type U. The tag distinguishes flag sets that share the same storage type and describes which bits are valid through the BitFlagsSpec trait.

Flag sets can be defined either through the bitflags! macro, which generates the trait implementation and named constants from a compact declaration, or by implementing BitFlagsSpec directly. Both forms produce the same types and the same runtime behavior.

The crate is no_std and no_alloc compatible, and const-friendly.

When to choose bitflags, bitflags-lite, or enumflags2

• Choose bitflags if you want the mature and battle-tested crate, and the ecosystem-standard macro, and the ability to extend each flag set with inherent methods or third-party trait implementations.
• Choose bitflags-lite if you want a reusable generic BitFlags<T, U> with a small, inspectable expansion, optionally generated by a concise macro, and you don’t need the ability to extend each flag set with inherent methods or third-party trait implementations.
• Choose enumflags2 if you want a single-flag type distinct from the set type, enum-variant-driven definitions, and match/iter over variants.

About

Macro-based bitflags crate generate a distinct struct for every flag set. Each invocation re-expands the full method set, and the resulting types share no common trait or type with one another. By contrast, bitflags-lite defines BitFlags<T, U> once and asks you to specialize it through a plain trait implementation. The provided bitflags! macro is a convenience wrapper that generates that trait impl and the named constants — it does not generate a new type.

Design Highlights:

• Single-flag vs. set distinction. BitFlag<T, U> represents one bit index. BitFlags<T, U> represents a set. They convert into each other and interoperate through the usual operators.
• Invalid bits are representable. A BitFlags value may contain bits not set in BitFlagsSpec::VALID_BITS_MASK; they are preserved by raw-bit operations and cleared by BitFlags::truncate, BitFlags::complement, and Not. Use BitFlags::is_valid to check.
• Const-friendly. Every constructor, accessor, and combinator on the concrete integer types is a const fn. The generic equivalents live in the BitFlagsExt and BitFlagExt extension traits.
• No allocation. Parsing and formatting work without alloc. The alloc feature only enriches error messages with the offending input.
• No hidden type generation. Even with the bitflags! macro, no new type is created per flag set. The macro builds on the same generic BitFlags<T, U>, so all flag sets remain one type family.

Usage

[dependencies]
bitflags-lite = "0.3.0"

With optional features:

[dependencies]
bitflags-lite = { version = "0.3.0", features = [ "serde", "bytemuck" ] }

Examples

With the bitflags! macro

The macro generates the tag type, the flag-set alias, the BitFlagsSpec implementation, and the named constants from one compact declaration:

use core::str::FromStr;

use bitflags_lite::{BitFlag, BitFlags, BitFlagsSpec, NameMatcher};

bitflags_lite::bitflags! {
    #![storage(u32)]

    pub struct PermissionsTag;

    pub bit READ  = 0, &["read"];
    pub bit WRITE = 1, &["write"];
    pub bit EXEC  = 2, &["exec", "execute"];

    pub mask RWX  = [READ, WRITE, EXEC], "rwx";
    pub mask NONE = 0, "none";
}

pub type Permission = BitFlag<u32, PermissionsTag>;
pub type Permissions = BitFlags<u32, PermissionsTag>;

let rwx = READ | WRITE | EXEC;
assert!(rwx.contains(READ.into()));
assert!(rwx.contains(WRITE.into()));
assert!(rwx.contains(EXEC.into()));
assert!(rwx.contains(RWX));

let read_exec = READ | EXEC;
assert!(!read_exec.contains(WRITE.into()));

// Combined names participate in parsing.
let parsed = Permissions::from_str("rwx").unwrap();
assert_eq!(format!("{parsed}"), "read | write | exec");

let parsed = Permissions::from_str("read | 0x18 | execute").unwrap();
assert_eq!(format!("{parsed}"), "read | exec | 0x18");

// Iteration yields individual BitFlag values.
let flags: Vec<Permission> = parsed.into_iter().collect();
assert_eq!(
    flags,
    [
        READ,
        EXEC,
        BitFlag::from_bit_retain(3),
        BitFlag::from_bit_retain(4),
    ]
);

let formatted: Vec<String> = flags.iter().map(ToString::to_string).collect();
assert_eq!(formatted, ["read", "exec", "0x8", "0x10"]);

let named_only: Vec<&'static str> = flags.iter().filter_map(BitFlag::name).collect();
assert_eq!(named_only, ["read", "exec"]);

Without the macro

The same flag set can be written manually. This is what the macro expands to, and it is fully supported as a public API:

use core::str::FromStr;

use bitflags_lite::{BitFlag, BitFlags, BitFlagsSpec, NameMatcher};

#[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Default, Debug)]
struct PermissionsTag;

impl BitFlagsSpec<u32> for PermissionsTag {
    const VALID_BITS_MASK: u32 = 0b111;
    const FLAG_NAMES: &[&[&str]] = &[&["read"], &["write"], &["exec", "execute"]];
    const COMBINED_NAMES: &[(u32, &str)] = &[(0, "none"), (0b111, "rwx")];
    const DEFAULT_NAME_MATCHER: NameMatcher = NameMatcher::Exact;
}

type Permission = BitFlag<u32, PermissionsTag>;
type Permissions = BitFlags<u32, PermissionsTag>;

// Constructors are `const` for concrete integer types.
const READ: Permission = Permission::try_from_bit(0).unwrap();
const WRITE: Permission = Permission::try_from_bit(1).unwrap();
const EXEC: Permission = Permission::try_from_bit(2).unwrap();
const RWX: Permissions = Permissions::try_from_bits(0b111).unwrap();

Constants can also be defined through an inherent implementation, a trait, or an associated const on the tag type.

Type-safety across flag sets

The tag type keeps flag sets distinct even when they share a storage type. The following example deliberately fails to compile:

use bitflags_lite::{BitFlags, BitFlagsSpec, NameMatcher};

struct PermsTag;
type Perms = BitFlags<u8, PermsTag>;
impl BitFlagsSpec<u8> for PermsTag {
    const VALID_BITS_MASK: u8 = (1 << 3) - 1;
    const FLAG_NAMES: &[&[&str]] = &[&["read"], &["write"], &["exec", "execute"]];
    const COMBINED_NAMES: &[(u8, &str)] = &[(0, "none"), (0b111, "rwx")];
    const DEFAULT_NAME_MATCHER: NameMatcher = NameMatcher::AsciiCaseInsensitive;
}

struct KeyboardModifiersTag;
type KeyboardModifiers = BitFlags<u8, KeyboardModifiersTag>;
impl BitFlagsSpec<u8> for KeyboardModifiersTag {
    const VALID_BITS_MASK: u8 = (1 << 4) - 1;
    const FLAG_NAMES: &[&[&str]] = &[&["Shift"], &["Ctrl"], &["Alt"], &["Meta"]];
    const COMBINED_NAMES: &[(u8, &str)] = &[];
    const DEFAULT_NAME_MATCHER: NameMatcher = NameMatcher::AsciiCaseInsensitive;
}

let rwx: Perms = Perms::try_from_bits(0b111).unwrap();
let keyboard_modifiers: KeyboardModifiers = rwx;
//                                          ^^^
// ❌ error[E0308]: mismatched types
// expected struct `BitFlags<_, KeyboardModifiersTag>`
//    found struct `BitFlags<_, test::PermsTag>`

Comparison with Existing Crates

Definition

Feature	bitflags-lite	bitflags v2	enumflags2 v0.7
Defined by trait impl	✅ BitFlagsSpec<T>	⛔️ No	⛔️ No
Defined by macro	✅ bitflags!	✅ bitflags!	⛔️ No
Defined by attribute	⛔️ No	⛔️ No	✅ #[bitflags(...)]
Generates a distinct new type	⛔️ No (generic over U)	✅ Yes	⛔️ No (uses user enum)

Type model

Feature	bitflags-lite	bitflags v2	enumflags2 v0.7
Single-flag vs. set distinction	✅ BitFlag / BitFlags	⛔️ No	✅ T / BitFlags
Iteration yields	BitFlag<T, U>	Flags (self, one bit)	enum T (variant)
Match exhaustively on single flag	⛔️ No	⛔️ No	✅ match flag { T::A => ... }
Generic over a single flag	✅ BitFlag<T, U>	⛔️ No	✅ enum T
Generic over flag sets	✅ BitFlags<T, U>	⛔️ No	✅ BitFlags<T, N>

Extension

Feature	bitflags-lite	bitflags v2	enumflags2 v0.7
Inherent methods	⛔️ No	✅ Yes	⛔️ No
Third-party trait impls	⛔️ No	✅ Yes	⛔️ No
Local trait impls	✅ Yes	✅ Yes	✅ Yes

Capabilities

Feature	bitflags-lite	bitflags v2	enumflags2 v0.7
Most methods const	✅ Integer impls	✅ Targeted codegen	⚠️ Limited
Multi-bit flags	⚠️ Parse-only	✅ Format and parse	⛔️ No
Custom display name	✅ Yes	✅ #[name]	⛔️ No
Alias names for parsing	✅ Yes	⛔️ No	⛔️ No
Format with names	✅ Yes	✅ Yes	✅ Yes
Parse from names	✅ Yes	✅ Yes	⛔️ No
Case-insensitive parsing	✅ Configurable	⛔️ No	⛔️ No
Custom default value	⛔️ No	✅ #[default]	✅ #[default]
Only valid bits representable	⛔️ No	⛔️ No	✅ Yes
Invalid bits representable	✅ Yes	✅ Yes	⛔️ No

Documentation

API Documentation

Feature flags

• alloc (implied by std, enabled by default): enriches parse errors with the offending input.
• std (enabled by default): enables the alloc feature.
• arbitrary: implements Arbitrary for BitFlag<T, U> and BitFlags<T, U>.
• serde: implements serde::Serialize and serde::Deserialize for BitFlag<T, U> and BitFlags<T, U>, round-tripping through flag strings.
• bytemuck: implements Zeroable and Pod for BitFlag<T, U> and BitFlags<T, U>, allowing them to be used in plain-old-data contexts.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Modules

util

Internal utilities for integer operations used by BitFlags.

Macros

bitflags

Defines a flag set from a compact declaration.

Structs

BitFlag

A single named or indexed bit in a BitFlags set.

BitFlagFromFlagsError

An error returned when converting BitFlags into a BitFlag fails.

BitFlagParseError

An error encountered while parsing flags from text.

BitFlagParseHexError

An error returned when parsing a hexadecimal flag fails.

BitFlagParseNameError

An error returned when parsing a named flag fails.

BitFlags

A type-safe set of flags stored in an integer T.

BitFlagsIter

An iterator over the individual bits set in a BitFlags value.

BitFlagsParseError

An error encountered while parsing flags from text.

Enums

NameMatcher

Controls how flag names are matched when parsing.

Traits

BitFlagExt

Extension trait providing generic, non-const equivalents of the type-specific inherent methods on BitFlag.

BitFlagsExt

Extension trait providing generic, non-const equivalents of the type-specific inherent methods on BitFlags.

BitFlagsSpec

Associates a bit-storage type T with the set of bits that are valid for a particular BitFlags tag.