third_party/rust/bitflags/README.md

   1 bitflags
   2 ========
   3
   4 [![Rust](https://github.com/bitflags/bitflags/workflows/Rust/badge.svg)](https://github.com/bitflags/bitflags/actions)
   5 [![Latest version](https://img.shields.io/crates/v/bitflags.svg)](https://crates.io/crates/bitflags)
   6 [![Documentation](https://docs.rs/bitflags/badge.svg)](https://docs.rs/bitflags)
   7 ![License](https://img.shields.io/crates/l/bitflags.svg)
   8
   9 `bitflags` generates flags enums with well-defined semantics and ergonomic end-user APIs.
  10
  11 You can use `bitflags` to:
  12
  13 - provide more user-friendly bindings to C APIs where flags may or may not be fully known in advance.
  14 - generate efficient options types with string parsing and formatting support.
  15
  16 You can't use `bitflags` to:
  17
  18 - 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.
  19 - define bitfields. `bitflags` only generates types where set bits denote the presence of some combination of flags.
  20
  21 - [Documentation](https://docs.rs/bitflags)
  22 - [Specification](https://github.com/bitflags/bitflags/blob/main/spec.md)
  23 - [Release notes](https://github.com/bitflags/bitflags/releases)
  24
  25 ## Usage
  26
  27 Add this to your `Cargo.toml`:
  28
  29 ```toml
  30 [dependencies]
  31 bitflags = "2.4.1"
  32 ```
  33
  34 and this to your source code:
  35
  36 ```rust
  37 use bitflags::bitflags;
  38 ```
  39
  40 ## Example
  41
  42 Generate a flags structure:
  43
  44 ```rust
  45 use bitflags::bitflags;
  46
  47 // The `bitflags!` macro generates `struct`s that manage a set of flags.
  48 bitflags! {
  49     /// Represents a set of flags.
  50     #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
  51     struct Flags: u32 {
  52         /// The value `A`, at bit position `0`.
  53         const A = 0b00000001;
  54         /// The value `B`, at bit position `1`.
  55         const B = 0b00000010;
  56         /// The value `C`, at bit position `2`.
  57         const C = 0b00000100;
  58
  59         /// The combination of `A`, `B`, and `C`.
  60         const ABC = Self::A.bits() | Self::B.bits() | Self::C.bits();
  61     }
  62 }
  63
  64 fn main() {
  65     let e1 = Flags::A | Flags::C;
  66     let e2 = Flags::B | Flags::C;
  67     assert_eq!((e1 | e2), Flags::ABC);   // union
  68     assert_eq!((e1 & e2), Flags::C);     // intersection
  69     assert_eq!((e1 - e2), Flags::A);     // set difference
  70     assert_eq!(!e2, Flags::A);           // set complement
  71 }
  72 ```
  73
  74 ## Rust Version Support
  75
  76 The minimum supported Rust version is documented in the `Cargo.toml` file.
  77 This may be bumped in minor releases as necessary.