Previously, the `from_bits` function in the `std::bitflags::bitflags`
macro was marked as unsafe, as it did not check that the bits being
converted actually corresponded to flags.
This patch changes the function to check against the full set of
possible flags and return an `Option` which is `None` if a non-flag bit
is set. It also adds a `from_bits_truncate` function which simply zeros
any bits not corresponding to a flag.
This addresses the concern raised in https://github.com/mozilla/rust/pull/13897
I feel that this is a very vital, missing piece of functionality. This adds on to #13072.
Only bits used in the definition of the bitflag are considered for the universe set. This is a bit safer than simply inverting all of the bits in the wrapped value.
```rust
bitflags!(flags Flags: u32 {
FlagA = 0x00000001,
FlagB = 0x00000010,
FlagC = 0x00000100,
FlagABC = FlagA.bits
| FlagB.bits
| FlagC.bits
})
...
// `Not` implements set complement
assert!(!(FlagB | FlagC) == FlagA);
// `all` and `is_all` are the inverses of `empty` and `is_empty`
assert!(Flags::all() - FlagA == !FlagA);
assert!(FlagABC.is_all());
```
The intent of `std::bitflags` is to allow building type-safe wrappers
around C-style flags APIs. But in addition to construction these flags
from the Rust side, we need a way to convert them from the C
side. This patch adds a `from_bits` function, which is unsafe since
the bits in question may not represent a valid combination of flags.
The `std::bitflags::bitflags!` macro did not provide support for
adding attributes to the generated structure or flags, due to
limitations in the parser for macros. This patch works around the
parser limitations by requiring a `flags` keyword in the overall
`bitflags!` invocation, and a `static` keyword for each flag:
bitflags!(
#[deriving(Hash)]
#[doc="Three flags"]
flags Flags: u32 {
#[doc="The first flag"]
static FlagA = 0x00000001,
static FlagB = 0x00000010,
static FlagC = 0x00000100
}
)
