bitflags

Example Code

// In Cargo.toml, add the following to your [dependencies] section:
// bitflags = "2.x"

use bitflags::bitflags;

// Define a set of flags for managing user permissions in a system.
// The 'bitflags!' macro generates a struct (UserPermissions) with associated constants
// for each flag and implements various useful traits and methods.
bitflags! {
    /// Represents different user permissions.
    /// Each flag corresponds to a specific permission that can be granted.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
    pub struct UserPermissions: u32 { // 'u32' specifies the underlying integer type
        const READ    = 0b0000_0001; // Can read resources
        const WRITE   = 0b0000_0010; // Can write/modify resources
        const EXECUTE = 0b0000_0100; // Can execute code or run applications
        const DELETE  = 0b0000_1000; // Can delete resources
        const ADMIN   = 0b1000_0000; // Has full administrative privileges (a high-level flag)

        // You can also define composite flags by combining existing ones.
        const RW = Self::READ.bits | Self::WRITE.bits;
        const CRUD_OPS = Self::READ.bits | Self::WRITE.bits | Self::DELETE.bits;
    }
}

fn main() {
    println!("--- bitflags Example: User Permissions ---");

    // 1. Creating flag combinations
    // Use the bitwise OR operator '|' to combine flags.
    let mut user1_perms = UserPermissions::READ | UserPermissions::WRITE;
    println!("User 1 Permissions: {:?}", user1_perms); // Output: UserPermissions(READ | WRITE)

    let user2_perms = UserPermissions::ADMIN;
    println!("User 2 Permissions: {:?}", user2_perms); // Output: UserPermissions(ADMIN)

    let user3_perms = UserPermissions::RW; // Using a predefined composite flag
    println!("User 3 Permissions (RW): {:?}", user3_perms); // Output: UserPermissions(READ | WRITE)

    // 2. Checking for specific flags
    println!("\n--- Checking Flags ---");
    println!("User 1 has READ permission: {}", user1_perms.contains(UserPermissions::READ));        // true
    println!("User 1 has EXECUTE permission: {}", user1_perms.contains(UserPermissions::EXECUTE)); // false
    println!("User 2 has ADMIN permission: {}", user2_perms.contains(UserPermissions::ADMIN));    // true

    // You can check if a set of flags contains another set.
    let required_perms = UserPermissions::READ | UserPermissions::WRITE;
    println!("User 1 has READ and WRITE: {}", user1_perms.contains(required_perms)); // true

    // 3. Modifying flags (inserting, removing, toggling, setting)
    println!("\n--- Modifying Flags ---");
    println!("Before modification, User 1: {:?}", user1_perms);

    user1_perms.insert(UserPermissions::EXECUTE); // Add EXECUTE permission
    println!("After inserting EXECUTE, User 1: {:?}", user1_perms); // UserPermissions(READ | WRITE | EXECUTE)

    user1_perms.remove(UserPermissions::WRITE); // Remove WRITE permission
    println!("After removing WRITE, User 1: {:?}", user1_perms);  // UserPermissions(READ | EXECUTE)

    user1_perms.toggle(UserPermissions::READ); // If present, remove; if absent, add
    println!("After toggling READ, User 1: {:?}", user1_perms);    // UserPermissions(EXECUTE)

    user1_perms.set(UserPermissions::DELETE, true); // Ensure DELETE is present
    println!("After setting DELETE to true, User 1: {:?}", user1_perms); // UserPermissions(EXECUTE | DELETE)

    user1_perms.set(UserPermissions::EXECUTE, false); // Ensure EXECUTE is absent
    println!("After setting EXECUTE to false, User 1: {:?}", user1_perms); // UserPermissions(DELETE)

    // 4. Bitwise operations (directly using operators)
    println!("\n--- Bitwise Operations ---");
    let p1 = UserPermissions::READ | UserPermissions::WRITE;
    let p2 = UserPermissions::WRITE | UserPermissions::DELETE;

    println!("P1: {:?}", p1);
    println!("P2: {:?}", p2);

    let combined_perms = p1 | p2; // Union: all flags present in either P1 or P2
    println!("P1 OR P2 (Union): {:?}", combined_perms); // UserPermissions(READ | WRITE | DELETE)

    let common_perms = p1 & p2; // Intersection: flags present in both P1 and P2
    println!("P1 AND P2 (Intersection): {:?}", common_perms); // UserPermissions(WRITE)

    let exclusive_perms = p1 ^ p2; // Symmetric difference: flags present in P1 or P2, but not both
    println!("P1 XOR P2 (Exclusive): {:?}", exclusive_perms); // UserPermissions(READ | DELETE)

    // 5. Checking intersection, emptiness, and all flags
    println!("\n--- Intersection & Emptiness ---");
    let current_perms = UserPermissions::READ | UserPermissions::EXECUTE;
    let target_perms = UserPermissions::WRITE | UserPermissions::EXECUTE;

    println!("Current perms: {:?}", current_perms);
    println!("Target perms: {:?}", target_perms);

    println!("Current perms intersects with Target perms: {}", current_perms.intersects(target_perms)); // true (due to EXECUTE)
    println!("Current perms contains Target perms: {}", current_perms.contains(target_perms));    // false (Current doesn't have WRITE)

    let empty_perms = UserPermissions::empty();
    println!("Empty permissions: {:?}", empty_perms); // UserPermissions(empty)
    println!("Is empty_perms really empty? {}", empty_perms.is_empty()); // true

    let all_defined_flags = UserPermissions::all(); // Contains all flags explicitly defined in the macro
    println!("All defined permissions: {:?}", all_defined_flags);
    println!("Are all flags set in 'all_defined_flags'? {}", all_defined_flags.is_all()); // true

    // Using the Default implementation (which often returns empty, depending on definition)
    let default_perms: UserPermissions = Default::default();
    println!("Default permissions: {:?}", default_perms); // UserPermissions(empty)
    assert_eq!(default_perms, UserPermissions::empty());
}