Arc<Mutex>

Guides

Rust walkthroughs

← Back to all guides

How does bitflags::Flags::from_bits_truncate handle undefined bit patterns compared to from_bits?

from_bits_truncate silently discards any bits not defined in the flags type, returning a value containing only the valid bits, while from_bits returns None if any undefined bits are present—from_bits_truncate provides lenient handling by masking away invalid bits, whereas from_bits enforces strict validity requiring all bits to be recognized. This difference makes from_bits_truncate suitable for parsing external input that may have reserved or future bits set, while from_bits is appropriate when bit patterns must be exactly representable.

The bitflags Crate and Bit Operations

use bitflags::bitflags;
 
bitflags! {
    #[derive(Debug, Clone, Copy)]
    struct Permissions: u8 {
        const READ = 0b0001;
        const WRITE = 0b0010;
        const EXECUTE = 0b0100;
    }
}
 
fn bitflags_basics() {
    // bitflags defines a struct with named bit values
    // Each constant represents one or more bits
    
    let perms = Permissions::READ | Permissions::WRITE;
    println!("{:?}", perms);  // READ | WRITE
    
    // The underlying bits are accessible
    println!("bits: {:04b}", perms.bits());  // 0011
    
    // Operations are type-safe
    if perms.contains(Permissions::READ) {
        println!("Has read permission");
    }
}

The bitflags! macro creates typesafe wrappers around bit patterns with named constants.

The from_bits Method

use bitflags::bitflags;
 
bitflags! {
    #[derive(Debug, Clone, Copy)]
    struct Permissions: u8 {
        const READ = 0b0001;
        const WRITE = 0b0010;
        const EXECUTE = 0b0100;
    }
}
 
fn from_bits_example() {
    // from_bits requires ALL bits to be defined
    
    // Valid bits: all bits are defined constants
    let valid = Permissions::from_bits(0b0111);
    assert_eq!(valid, Some(Permissions::all()));  // READ | WRITE | EXECUTE
    
    // Valid bits with subset
    let subset = Permissions::from_bits(0b0011);
    assert_eq!(subset, Some(Permissions::READ | Permissions::WRITE));
    
    // Invalid bits: undefined bit is set
    let invalid = Permissions::from_bits(0b1001);  // Bit 3 is undefined
    assert_eq!(invalid, None);
    
    // from_bits returns None if ANY bit is not defined
    // This is strict: all bits must be known
}

from_bits returns Option<Flags>—None if any undefined bit is set.

The from_bits_truncate Method

use bitflags::bitflags;
 
bitflags! {
    #[derive(Debug, Clone, Copy)]
    struct Permissions: u8 {
        const READ = 0b0001;
        const WRITE = 0b0010;
        const EXECUTE = 0b0100;
    }
}
 
fn from_bits_truncate_example() {
    // from_bits_truncate masks away undefined bits
    
    // Valid bits: same as from_bits
    let valid = Permissions::from_bits_truncate(0b0111);
    assert_eq!(valid, Permissions::all());  // READ | WRITE | EXECUTE
    
    // Invalid bits: undefined bits are removed
    let with_invalid = Permissions::from_bits_truncate(0b1001);  // Bit 3 undefined
    assert_eq!(with_invalid, Permissions::READ);  // Only bit 0 (READ) kept
    
    // Multiple undefined bits
    let more_invalid = Permissions::from_bits_truncate(0b1111);  // Bits 3 undefined
    assert_eq!(more_invalid, Permissions::READ | Permissions::WRITE | Permissions::EXECUTE);
    
    // from_bits_truncate ALWAYS returns a valid flags value
}

from_bits_truncate returns Flags directly—it removes undefined bits and always succeeds.

The Fundamental Difference

use bitflags::bitflags;
 
bitflags! {
    #[derive(Debug, Clone, Copy)]
    struct Flags: u8 {
        const A = 0b0001;
        const B = 0b0010;
        const C = 0b0100;
    }
}
 
fn fundamental_difference() {
    let input: u8 = 0b1011;  // Bits: A, B, and undefined bit 3
    
    // from_bits: Strict validation
    match Flags::from_bits(input) {
        Some(flags) => println!("Valid: {:?}", flags),
        None => println!("Invalid: contains undefined bits"),
    }
    // Output: "Invalid: contains undefined bits"
    
    // from_bits_truncate: Lenient handling
    let truncated = Flags::from_bits_truncate(input);
    println!("Truncated: {:?}", truncated);
    // Output: "Truncated: A | B"
    // Bit 3 was removed, bits 0 and 1 kept
    
    // Use from_bits when:
    // - Input must be exactly valid
    // - Undefined bits indicate error
    // - Strict validation required
    
    // Use from_bits_truncate when:
    // - Input may have reserved/future bits
    // - Undefined bits should be ignored
    // - Forward compatibility needed
}

from_bits enforces strict validity; from_bits_truncate provides forward compatibility.

Return Type Difference

use bitflags::bitflags;
 
bitflags! {
    #[derive(Debug, Clone, Copy)]
    struct Status: u8 {
        const ACTIVE = 0b0001;
        const PENDING = 0b0010;
    }
}
 
fn return_types() {
    // from_bits returns Option<Flags>
    // Must handle the None case
    let result: Option<Status> = Status::from_bits(0b0011);
    
    match result {
        Some(status) => println!("Status: {:?}", status),
        None => println!("Invalid status bits"),
    }
    
    // from_bits_truncate returns Flags directly
    // Always succeeds, no Option
    let result: Status = Status::from_bits_truncate(0b1011);
    // Can use directly without unwrapping
    println!("Status: {:?}", result);
    
    // The truncated result is always valid
    assert!(result.bits() == 0b0011);  // Undefined bit removed
}

from_bits returns Option<Flags> requiring handling; from_bits_truncate returns Flags directly.

Practical Use Case: Parsing External Input

use bitflags::bitflags;
 
bitflags! {
    #[derive(Debug, Clone, Copy)]
    struct FileFlags: u32 {
        const READ = 0b0001;
        const WRITE = 0b0010;
        const EXECUTE = 0b0100;
        const HIDDEN = 0b1000;
    }
}
 
fn parse_file_flags() {
    // Scenario: Parsing flags from external source
    // External systems may use bits we don't define
    
    // Example: Reading flags from a file format
    // File format reserves bits 4-31 for future use
    let external_flags: u32 = 0b0000_1111_0000_0001;  // Includes reserved bits
    
    // Using from_bits would fail
    match FileFlags::from_bits(external_flags) {
        Some(flags) => {
            // Won't reach here
            println!("Flags: {:?}", flags);
        }
        None => {
            // Would always fail if reserved bits are set
            println!("Cannot parse: undefined bits present");
        }
    }
    
    // Using from_bits_truncate handles it gracefully
    let parsed = FileFlags::from_bits_truncate(external_flags);
    println!("Parsed flags: {:?}", parsed);
    // Only known bits (READ, WRITE, EXECUTE, HIDDEN) are kept
    
    // This enables forward compatibility:
    // - Newer versions can define additional flags
    // - Older versions ignore unknown bits
    // - No parsing errors from reserved bits
}

from_bits_truncate enables forward compatibility when parsing external or evolving bit patterns.

Practical Use Case: Network Protocol Parsing

use bitflags::bitflags;
 
bitflags! {
    #[derive(Debug, Clone, Copy)]
    struct TcpFlags: u8 {
        const FIN = 0b00000001;
        const SYN = 0b00000010;
        const RST = 0b00000100;
        const PSH = 0b00001000;
        const ACK = 0b00010000;
        const URG = 0b00100000;
        // Bits 6-7 are reserved/undefined
    }
}
 
fn parse_tcp_flags() {
    // TCP flags may have reserved bits set
    let raw_flags: u8 = 0b11000010;  // SYN + reserved bits
    
    // from_bits would reject this
    assert!(TcpFlags::from_bits(raw_flags).is_none());
    
    // from_bits_truncate extracts valid flags
    let flags = TcpFlags::from_bits_truncate(raw_flags);
    assert_eq!(flags, TcpFlags::SYN);  // Reserved bits removed
    
    // This is appropriate for network protocols:
    // - Reserved bits may be set by future protocol versions
    // - We should ignore unknown bits, not fail
    // - Backward/forward compatibility
}

Network protocols often have reserved bits; from_bits_truncate handles them gracefully.

Practical Use Case: System Call Flags

use bitflags::bitflags;
 
bitflags! {
    #[derive(Debug, Clone, Copy)]
    struct OpenFlags: i32 {
        const O_RDONLY = 0;
        const O_WRONLY = 1;
        const O_RDWR = 2;
        const O_CREAT = 0o100;
        const O_TRUNC = 0o200;
        const O_APPEND = 0o1000;
        // Many more flags exist on various platforms
    }
}
 
fn parse_system_flags() {
    // System calls may return platform-specific bits
    
    let raw_flags: i32 = 0o1700;  // O_CREAT | O_TRUNC | unknown bit
    
    // Option 1: Strict validation (for user input)
    match OpenFlags::from_bits(raw_flags) {
        Some(flags) => {
            println!("Valid flags: {:?}", flags);
        }
        None => {
            println!("Error: unknown flags specified");
            // User input should be validated strictly
        }
    }
    
    // Option 2: Lenient parsing (for system values)
    let parsed = OpenFlags::from_bits_truncate(raw_flags);
    println!("Known flags: {:?}", parsed);
    // Extracts O_CREAT | O_TRUNC, ignores unknown
    
    // This is appropriate for:
    // - Reading system call results
    // - Handling platform-specific flags
    // - Logging unknown flags separately
}

System interfaces may have platform-specific bits; truncation handles cross-platform differences.

The from_bits_retain Method

use bitflags::bitflags;
 
bitflags! {
    #[derive(Debug, Clone, Copy)]
    struct Config: u8 {
        const DEBUG = 0b0001;
        const VERBOSE = 0b0010;
        const QUIET = 0b0100;
    }
}
 
fn from_bits_retain_example() {
    // There's also from_bits_retain (bitflags 2.x)
    // It keeps undefined bits in the value
    
    // Note: This requires unsafe or specific configuration
    // to actually preserve the bits
    
    // from_bits_truncate: removes undefined bits
    // from_bits_retain: keeps undefined bits (unsafe)
    // from_bits: rejects undefined bits
    
    // In practice, from_bits_retain is rarely used
    // Most use cases want either strict (from_bits)
    // or lenient (from_bits_truncate) handling
}

from_bits_retain is a third option that preserves undefined bits, but is less commonly used.

Comparison with Other Constructors

use bitflags::bitflags;
 
bitflags! {
    #[derive(Debug, Clone, Copy)]
    struct Mode: u8 {
        const READ = 0b001;
        const WRITE = 0b010;
        const EXECUTE = 0b100;
    }
}
 
fn constructors_comparison() {
    // Multiple ways to create flags:
    
    // 1. Empty
    let empty = Mode::empty();
    assert_eq!(empty.bits(), 0);
    
    // 2. All defined flags
    let all = Mode::all();
    assert_eq!(all.bits(), 0b111);
    
    // 3. From bits (strict)
    let strict = Mode::from_bits(0b011);
    assert_eq!(strict, Some(Mode::READ | Mode::WRITE));
    
    // 4. From bits (truncate)
    let truncated = Mode::from_bits_truncate(0b1111);
    assert_eq!(truncated, Mode::all());  // Bit 3 removed
    
    // 5. From bits (unsafe, retain)
    // let retained = Mode::from_bits_retain(0b1111);
    // Keeps bit 3, but requires unsafe
    
    // 6. Combine with bitwise operations
    let combined = Mode::READ | Mode::WRITE;
    assert_eq!(combined.bits(), 0b011);
    
    // 7. From bits (unchecked)
    // let unchecked = unsafe { Mode::from_bits_unchecked(0b1111) };
    // Keeps all bits, caller guarantees validity
}

Multiple constructors provide different guarantees; from_bits and from_bits_truncate are the most common.

Checking for Unknown Bits

use bitflags::bitflags;
 
bitflags! {
    #[derive(Debug, Clone, Copy)]
    struct Flags: u8 {
        const A = 0b001;
        const B = 0b010;
        const C = 0b100;
    }
}
 
fn check_unknown_bits() {
    let raw: u8 = 0b1011;  // A | B | unknown bit 3
    
    // Check if any bits are unknown
    let flags = Flags::from_bits_truncate(raw);
    
    // Compare truncated with original
    if flags.bits() != raw {
        let unknown_bits = raw & !Flags::all().bits();
        println!("Warning: unknown bits {:08b}", unknown_bits);
    }
    
    // Alternative: check with from_bits
    if Flags::from_bits(raw).is_none() {
        println!("Warning: input contains undefined bits");
        // Then use from_bits_truncate if you still want to proceed
        let flags = Flags::from_bits_truncate(raw);
    }
    
    // Or use the is_all() method
    // To check if a value contains all defined flags
}

You can detect unknown bits by comparing truncated value to original.

Working with Reserved Bits

use bitflags::bitflags;
 
bitflags! {
    #[derive(Debug, Clone, Copy)]
    struct ConfigBits: u16 {
        // Lower byte: active configuration
        const ENABLED = 0b0000_0000_0000_0001;
        const DEBUG = 0b0000_0000_0000_0010;
        const TRACE = 0b0000_0000_0000_0100;
        
        // Upper byte: reserved for future use
        // Currently undefined
    }
}
 
fn reserved_bits() {
    // Configuration from external source
    let config_value: u16 = 0x0307;  // DEBUG | TRACE | ENABLED + reserved bits
    
    // Future-compatible parsing
    let config = ConfigBits::from_bits_truncate(config_value);
    
    println!("Active config: {:?}", config);
    // ENABLED | DEBUG | TRACE
    
    // Reserved bits (0x0300) are safely ignored
    // Future versions can define them:
    // const FUTURE_FEATURE = 0x0100;
    
    // This enables:
    // - Older code running on newer data
    // - Newer code defining new flags
    // - No data migration needed
}

Reserved bits for future use are gracefully handled by from_bits_truncate.

Implementation Details

use bitflags::bitflags;
 
bitflags! {
    #[derive(Debug, Clone, Copy)]
    struct Flags: u8 {
        const A = 1;
        const B = 2;
        const C = 4;
    }
}
 
fn implementation_details() {
    // from_bits essentially does:
    // fn from_bits(bits: u8) -> Option<Flags> {
    //     if bits & !Self::all().bits() != 0 {
    //         None  // Unknown bits present
    //     } else {
    //         Some(Flags { bits })
    //     }
    // }
    
    // from_bits_truncate essentially does:
    // fn from_bits_truncate(bits: u8) -> Flags {
    //     Flags { bits: bits & Self::all().bits() }
    // }
    
    // The key difference:
    // - from_bits CHECKS for unknown bits, returns None if found
    // - from_bits_truncate MASKS away unknown bits
    
    // Example with the actual methods:
    let with_unknown = 0b1111u8;  // A | B | C | unknown
    
    // from_bits checks
    assert!(Flags::from_bits(with_unknown).is_none());
    // because (0b1111 & !0b0111) != 0
    
    // from_bits_truncate masks
    let truncated = Flags::from_bits_truncate(with_unknown);
    assert_eq!(truncated.bits(), 0b0111);  // 0b1111 & 0b0111
}

The implementation difference: from_bits checks for unknown bits; from_bits_truncate masks them away.

Summary Table

fn summary() {
    // | Method | Returns | Undefined Bits | Use Case |
    // |--------|---------|----------------|----------|
    // | from_bits | Option<Flags> | None returned | Strict validation |
    // | from_bits_truncate | Flags | Masked away | Forward compatibility |
    // | from_bits_retain | Flags | Preserved (unsafe) | Low-level bit manipulation |
    // | from_bits_unchecked | Flags | Preserved (caller responsibility) | Performance-critical |
    
    // | Input Bits | from_bits | from_bits_truncate |
    // |------------|-----------|---------------------|
    // | All defined | Some(flags) | flags |
    // | Some undefined | None | flags with undefined removed |
    // | All undefined | None | empty flags |
    // | Zero | Some(empty) | empty flags |
    
    // | Scenario | Recommended Method |
    // |----------|-------------------|
    // | User input validation | from_bits |
    // | External protocol parsing | from_bits_truncate |
    // | System call return values | from_bits_truncate |
    // | Versioned data formats | from_bits_truncate |
    // | Strict type safety | from_bits |
    // | Cross-platform compatibility | from_bits_truncate |
}

Synthesis

Quick reference:

use bitflags::bitflags;
 
bitflags! {
    #[derive(Debug, Clone, Copy)]
    struct Flags: u8 {
        const A = 0b001;
        const B = 0b010;
        const C = 0b100;
    }
}
 
fn quick_reference() {
    let all_defined = 0b011u8;     // A | B
    let with_unknown = 0b1111u8;   // A | B | C | unknown
    
    // from_bits: strict validation
    assert_eq!(Flags::from_bits(all_defined), Some(Flags::A | Flags::B));
    assert_eq!(Flags::from_bits(with_unknown), None);
    
    // from_bits_truncate: lenient parsing
    assert_eq!(Flags::from_bits_truncate(all_defined), Flags::A | Flags::B);
    assert_eq!(Flags::from_bits_truncate(with_unknown), Flags::A | Flags::B | Flags::C);
    //                                            Unknown bit removed ^^^
}

Key insight: from_bits and from_bits_truncate represent two philosophies for handling unknown bit patterns. from_bits enforces strict validity—all bits must be defined, and unknown bits signal an error. This is appropriate for user input validation, configuration files, and other scenarios where invalid input should be rejected. from_bits_truncate provides leniency—unknown bits are silently removed, and the result always contains only defined flags. This is appropriate for parsing external data, network protocols, system call results, and versioned formats where reserved bits may be set by newer implementations. The return types reflect this: from_bits returns Option<Flags> because parsing might fail; from_bits_truncate returns Flags directly because it always succeeds. Choose from_bits when you need strict validation and should reject unknown bits; choose from_bits_truncate when you need forward compatibility and should gracefully ignore unknown bits.