Add an option for checking for valid bits is in the getter rather than constructor

[CasperN]

Hi, I want to use bitflags for generated code that interacts with data in other languages, some of which are bitflags (google/flatbuffers#6098). I don't want to drop data so I'd like to use from_bits_unchecked. However, it is marked as unsafe. I'd like to submit a PR to add an option to get around this. I have two ideas:

1. Move the valid-bits-check to the getter: There'll be only one constructor: from_bits and the bits() getter becomes bits() -> Result<...>, unsafe bits_unchecked(), and bits_truncated()

2. Document why from_bits_unchecked is unsafe #200 documents that this crate uses unsafe to mean a usage issue rather than a memory issue, so maybe I could make an option to remove the unsafe altogether, and update the generated documentation appropriately?

What are your thoughts on these ideas? Does bitflags depend on the "bits are truncated to defined flags" invariant?

[sollyucko]

Related: #188, #200, #207, #208, #211

[CasperN]

@niklasf @KodrAus worked on #200

[CasperN]

Bump!

I'll do the PR if needed

[KodrAus]

Hi @CasperN! 👋

We can't consider any changes to the bits() method, because the library is already stable.

The way we modeled this originally was that the flags represents a closed enum, where the set specified in the definition is the complete set of possible flags the enum could combine. Since not all valid bit patterns of the underlying integer type are valid bit patterns of the flags it's not safe for us to simply accept any integer and treat it as valid flags. So we made the unchecked method unsafe.

If we wanted to clean up the semantics we could consider allowing an #[open] attribute or something on the bitflags! definition itself, so you'd declare an open bitflags that could happily accept any integer, assuming it's not the source-of-truth for what flags exist:

bitflags! {
    #[open]
    struct Flags: u32 {
        const A = 0b00000001;
        const B = 0b00000010;
    }
}

Then let these #[open] bitflags have #[repr(transparent)] and so can be soundly transmuted to and from the given integer type, making from_bits_unchecked safe.

What do you think?

[KodrAus]

We could also use #[repr(transparent)] for this. I don’t think that’s too much of a semantic hijacking, so long as it also does apply the attribute.