diff options
Diffstat (limited to 'vendor/bitflags/README.md')
| -rw-r--r-- | vendor/bitflags/README.md | 77 |
1 files changed, 77 insertions, 0 deletions
diff --git a/vendor/bitflags/README.md b/vendor/bitflags/README.md new file mode 100644 index 0000000..ecad515 --- /dev/null +++ b/vendor/bitflags/README.md @@ -0,0 +1,77 @@ +bitflags +======== + +[](https://github.com/bitflags/bitflags/actions) +[](https://crates.io/crates/bitflags) +[](https://docs.rs/bitflags) + + +`bitflags` generates flags enums with well-defined semantics and ergonomic end-user APIs. + +You can use `bitflags` to: + +- provide more user-friendly bindings to C APIs where flags may or may not be fully known in advance. +- generate efficient options types with string parsing and formatting support. + +You can't use `bitflags` to: + +- guarantee only bits corresponding to defined flags will ever be set. `bitflags` allows access to the underlying bits type so arbitrary bits may be set. +- define bitfields. `bitflags` only generates types where set bits denote the presence of some combination of flags. + +- [Documentation](https://docs.rs/bitflags) +- [Specification](https://github.com/bitflags/bitflags/blob/main/spec.md) +- [Release notes](https://github.com/bitflags/bitflags/releases) + +## Usage + +Add this to your `Cargo.toml`: + +```toml +[dependencies] +bitflags = "2.4.1" +``` + +and this to your source code: + +```rust +use bitflags::bitflags; +``` + +## Example + +Generate a flags structure: + +```rust +use bitflags::bitflags; + +// The `bitflags!` macro generates `struct`s that manage a set of flags. +bitflags! { + /// Represents a set of flags. + #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] + struct Flags: u32 { + /// The value `A`, at bit position `0`. + const A = 0b00000001; + /// The value `B`, at bit position `1`. + const B = 0b00000010; + /// The value `C`, at bit position `2`. + const C = 0b00000100; + + /// The combination of `A`, `B`, and `C`. + const ABC = Self::A.bits() | Self::B.bits() | Self::C.bits(); + } +} + +fn main() { + 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 + +The minimum supported Rust version is documented in the `Cargo.toml` file. +This may be bumped in minor releases as necessary. |