Allow for masking using a different datatype

[Susurrus]

I work with data that often has a set of bitflags and then also has various masks defined over those bitflags. Unfortunately those masks are not often a valid value for the actual datatype. For example, when working with the termios API on POSIX systems, you have the constants:

bitflags! {
    pub flags ControlFlags: tcflag_t {
        ...,
        CS5,
        CS6,
        CS7,
        CS8,
        ...,
    }
}

This is part of a larger bitfield that contains many other values, so the following flags are defined:

bitflags! {
    pub flags ControlFlagsMask: tcflag_t {
        ...,
        CSIZE,
        ...,
    }
}

But if I do this, there's no way to actually do set operations between these two without combining these flags, which creates the problem of a user actually being able to generate an invalid bitfield by using CSIZE directly and passing it into a function.

It'd be great if there was a way to tag certain values as a mask such that you could use it to select values from an existing bitflags type but couldn't use it directly within that type.

[Susurrus]

Another way to think of this is that the bitfield could actually be broken up into bit groups, and those would each have a mask value. In my case, the groups are defined by bit masks that can vary by platform, so I would want to specify those explicitly. But for others, it might make sense to allow masks to be automatically generated based on existing values and the user just needs to specify a name.

[dtolnay]

You are free to implement set operations yourself.

#[macro_use]
extern crate bitflags;

extern crate libc;
use libc::tcflag_t;

use std::ops::BitAnd;

bitflags! {
    pub struct ControlFlags: tcflag_t {
        const CS5   = 0b00001;
        const CS6   = 0b00010;
        const CS7   = 0b00100;
        const CS8   = 0b01000;
        const CREAD = 0b10000;
    }
}

bitflags! {
    pub struct ControlFlagsMask: tcflag_t {
        const CSIZE = 0b01111;
    }
}

impl BitAnd<ControlFlagsMask> for ControlFlags {
    type Output = Self;

    fn bitand(self, rhs: ControlFlagsMask) -> Self {
        Self::from_bits_truncate(self.bits() & rhs.bits())
    }
}

fn main() {
    let flags = CS8 | CREAD;
    println!("input: {:?}", flags);
    println!("size flags: {:?}", flags & CSIZE);
    println!("all size flags: {:?}", ControlFlags::all() & CSIZE);
}

[Susurrus]

@dtolnay Sorry I never responded to this. I take it there's no interest in supporting this directly by the bitflags library? I would be willing to write up a PR, but i opened this issue to get initial feedback before spending my time coding it up.

[dtolnay]

I think the concept of a mask that is an illegal value of the type is higher-level than what bitflags aims to provide. The concept of bitflags here is a set, a handful of constructors for that set, and an underlying representation as an integer.

const CS5 = 0b00001;
const CS6 = 0b00010;
const CS7 = 0b00100;
const CS8 = 0b01000;

#[illegal_and_only_for_use_in_mask_operations]
const MASK = 0b01111;

These are just sets so CS5 | CS6 | CS7 | CS8 has no problem giving you the "illegal" value.

If your type is conceptually a set, treating the mask as a different type may at least make some APIs clearer. BitAnd is the usual way in Rust to define the & operator across different types.

If your type is conceptually not a set than bitflags isn't really the right abstraction, though it may still be useful in the private implementation of some more unique public API.

[Susurrus]

Yeah, that's a good point. In actuality I deal very rarely with pure sets, instead theyre a combination of fields that are mutually-exclusive options and binary bitflags. The current bitflags implementation here starts to break down past these pure-binary-option types (which are inherently mutually exclusive) and multi-bit fields that are not enforced to be mutually exclusive.

So maybe this issue pertains to the larger question you at least partially discussed above, whether bitflags aims to also address these heterogeneous bitfields (where some fields within it are multiple-bits with mutually exclusive options). You state it does not and I wanted to clarify this is indeed out of scope for this library.