Wrap generated flags types in a newtype

Cargo.toml

@@ -16,22 +16,24 @@ categories = ["no-std"]
 description = """
 A macro to generate structures which behave like bitflags.
 """
-exclude = ["bors.toml"]
+exclude = [
+    ".github"
+]
 
 [dependencies]
-core = { version = '1.0.0', optional = true, package = 'rustc-std-workspace-core' }
-compiler_builtins = { version = '0.1.2', optional = true }
+core = { version = "1.0.0", optional = true, package = 'rustc-std-workspace-core' }
+compiler_builtins = { version = "0.1.2", optional = true }
+serde = { version = "1", optional = true }
 
 [dev-dependencies]
 trybuild = "1.0"
 rustversion = "1.0"
 walkdir = "2.3"
 serde = "1.0"
 serde_derive = "1.0"
-serde_json = "1.0"
+serde_test = "1.0"
 
 [features]
-default = []
 example_generated = []
 rustc-dep-of-std = ["core", "compiler_builtins"]
 

README.md

@@ -1,32 +1,49 @@
-bitflags
-========
+# `bitflags`
 
 [![Rust](https://github.com/bitflags/bitflags/workflows/Rust/badge.svg)](https://github.com/bitflags/bitflags/actions)
-[![Join the chat at https://gitter.im/bitflags/Lobby](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/bitflags/Lobby?utm_source=badge&utm_medium=badge&utm_content=badge)
 [![Latest version](https://img.shields.io/crates/v/bitflags.svg)](https://crates.io/crates/bitflags)
 [![Documentation](https://docs.rs/bitflags/badge.svg)](https://docs.rs/bitflags)
 ![License](https://img.shields.io/crates/l/bitflags.svg)
 
-A Rust macro to generate structures which behave like a set of bitflags
+A Rust macro to generate structures which behave like a set of bitflags.
 
 - [Documentation](https://docs.rs/bitflags)
 - [Release notes](https://github.com/bitflags/bitflags/releases)
 
-## Usage
+## Getting stareted
 
 Add this to your `Cargo.toml`:
 
 ```toml
-[dependencies]
-bitflags = "1.3"
+[dependencies.bitflags]
+version = "1.3"
 ```
 
-and this to your source code:
+Use the `bitflags!` macro to define a bitflags type:
 
 ```rust
 use bitflags::bitflags;
+
+bitflags! {
+    #[derive(PartialEq)]
+    struct Flags: u32 {
+        const A = 0b00000001;
+        const B = 0b00000010;
+        const C = 0b00000100;
+        const ABC = Self::A.bits() | Self::B.bits() | Self::C.bits();
+    }
+}
+
+let e1 = Flags::A | Flags::C;
+let e2 = Flags::B | Flags::C;
+
+assert_eq!((e1 | e2), Flags::ABC);   // union
+assert_eq!((e1 & e2), Flags::C);     // intersection
+assert_eq!((e1 - e2), Flags::A);     // set difference
+assert_eq!(!e2, Flags::A);           // set complement
 ```
 
-## Rust Version Support
+## Minimum Supported Rust Version (MSRV)
 
 The minimum supported Rust version is 1.46 due to use of associated constants and const functions.
+This version may be bumped in minor releases.

src/bitflags_trait.rs

@@ -6,6 +6,7 @@ pub trait ImplementedByBitFlagsMacro {}
 /// It should not be implemented manually.
 pub trait BitFlags: ImplementedByBitFlagsMacro {
     type Bits;
+
     /// Returns an empty set of flags.
     fn empty() -> Self;
     /// Returns the set containing all flags.
@@ -21,16 +22,7 @@ pub trait BitFlags: ImplementedByBitFlagsMacro {
     fn from_bits_truncate(bits: Self::Bits) -> Self;
     /// Convert from underlying bit representation, preserving all
     /// bits (even those not corresponding to a defined flag).
-    ///
-    /// # Safety
-    ///
-    /// The caller of the `bitflags!` macro can chose to allow or
-    /// disallow extra bits for their bitflags type.
-    ///
-    /// The caller of `from_bits_unchecked()` has to ensure that
-    /// all bits correspond to a defined flag or that extra bits
-    /// are valid for this bitflags type.
-    unsafe fn from_bits_unchecked(bits: Self::Bits) -> Self;
+    fn from_bits_preserve(bits: Self::Bits) -> Self;
     /// Returns `true` if no flags are currently stored.
     fn is_empty(&self) -> bool;
     /// Returns `true` if all flags are currently set.

src/example_generated.rs

@@ -9,6 +9,6 @@ bitflags! {
         const A = 0b00000001;
         const B = 0b00000010;
         const C = 0b00000100;
-        const ABC = Self::A.bits | Self::B.bits | Self::C.bits;
+        const ABC = Self::A.bits() | Self::B.bits() | Self::C.bits();
     }
 }