2026-01-24 22:59:20 +00:00
rust
ßb � §Ì± ‘ ’ › � |6¨%Œ
+
std_detectÁMmáýZ^9õ Îà§e˜÷e � .Å"ÒÜuPp¹ˆ¶
µT§� 5 � tGNÏ � � ‘ � � ‘ ‘ � '� ' ’ ‘
œÆå
impl WriteÁ
empty_flagÁ
˜
is_unnamedÁ
iter_namesÁ
intersectsÁ
differenceÁ
complementÁ – – � –
¸ ¸
ParseErrorÁ
� � �
�
‚
ˆ
ˆ
‹
�
� Ô±ël–ÏS � –
� šË¹1
– ‘ � � � � ‘ – �
˜
¸
³* � ‹
,Ø
‹ ‹ ¸
� :
˜ � ‘
� –
usize::MAXÁ � T � 0
� �
üÞ7!
Generate types for C-style flags with ergonomic APIs.
# Getting started
Add `bitflags` to your `Cargo.toml`:
```toml
[dependencies.bitflags]
version = "2.10.0"
```
## Crate features
The `bitflags` library defines a few Cargo features that you can opt-in to:
- `std`: Implement the `Error` trait on error types used by `bitflags`.
- `serde`: Support deriving `serde` traits on generated flags types.
- `arbitrary`: Support deriving `arbitrary` traits on generated flags types.
- `bytemuck`: Support deriving `bytemuck` traits on generated flags types.
## Generating flags types
Use the [`bitflags`] macro to generate flags types:
```rust
use bitflags::bitflags;
bitflags! {
pub struct Flags: u32 {
const A = 0b00000001;
const B = 0b00000010;
const C = 0b00000100;
}
}
```
See the docs for the `bitflags` macro for the full syntax.
Also see the [`example_generated`](./example_generated/index.html) module for an example of what the `bitflags` macro generates for a flags type.
### Externally defined flags
If you're generating flags types for an external source, such as a C API, you can define
an extra unnamed flag as a mask of all bits the external source may ever set. Usually this would be all bits (`!0`):
```rust
# use bitflags::bitflags;
bitflags! {
pub struct Flags: u32 {
const A = 0b00000001;
const B = 0b00000010;
const C = 0b00000100;
// The source may set any bits
const _ = !0;
}
}
```
Why should you do this? Generated methods like `all` and truncating operators like `!` only consider
bits in defined flags. Adding an unnamed flag makes those methods consider additional bits,
without generating additional constants for them. It helps compatibility when the external source
may start setting additional bits at any time. The [known and unknown bits](#known-and-unknown-bits)
section has more details on this behavior.
### Custom derives
You can derive some traits on generated flags types if you enable Cargo features. The following
libraries are currently supported:
- `serde`: Support `#[derive(Serialize, Deserialize)]`, using text for human-readable formats,
and a raw number for binary formats.
- `arbitrary`: Support `#[derive(Arbitrary)]`, only generating flags values with known bits.
- `bytemuck`: Support `#[derive(Pod, Zeroable)]`, for casting between flags values and their
underlying bits values.
You can also define your own flags type outside of the [`bitflags`] macro and then use it to generate methods.
This can be useful if you need a custom `#[derive]` attribute for a library that `bitflags` doesn't
natively support:
```rust
# use std::fmt::Debug as SomeTrait;
# use bitflags::bitflags;
#[derive(SomeTrait)]
pub struct Flags(u32);
bitflags! {
impl Flags: u32 {
const A = 0b00000001;
const B = 0b00000010;
const C = 0b00000100;
}
}
```
### Adding custom methods
The [`bitflags`] macro supports attributes on generated flags types within the macro itself, while
`impl` blocks can be added outside of it:
```rust
# use bitflags::bitflags;
bitflags! {
// Attributes can be applied to flags types
#[repr(transparent)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Flags: u32 {
const A = 0b00000001;
const B = 0b00000010;
const C = 0b00000100;
}
}
// Impl blocks can be added to flags types
impl Flags {
pub fn as_u64(&self) -> u64 {
self.bits() as u64
}
}
```
## Working with flags values
Use generated constants and standard bitwise operators to interact with flags values:
```rust
# use bitflags::bitflags;
# bitflags! {
# #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
# pub struct Flags: u32 {
# const A = 0b00000001;
# const B = 0b00000010;
# const C = 0b00000100;
# }
# }
// union
let ab = Flags::A | Flags::B;
// intersection
let a = ab & Flags::A;
// difference
let b = ab - Flags::A;
// complement
let c = !ab;
```
See the docs for the [`Flags`] trait for more details on operators and how they behave.
# Formatting and parsing
`bitflags` defines a text format that can be used to convert any flags value to and from strings.
See the [`parser`] module for more details.
# Specification
The terminology and behavior of generated flags types is
[specified in the source repository](https://github.com/bitflags/bitflags/blob/main/spec.md).
Details are repeated in these docs where appropriate, but is exhaustively listed in the spec. Some
things are worth calling out explicitly here.
## Flags types, flags values, flags
The spec and these docs use consistent terminology to refer to things in the bitflags domain:
- **Bits type**: A type that defines a fixed number of bits at specific locations.
- **Flag**: A set of bits in a bits type that may have a unique name.
- **Flags type**: A set of defined flags over a specific bits type.
- **Flags value**: An instance of a flags type using its specific bits value for storage.
```
# use bitflags::bitflags;
bitflags! {
struct FlagsType: u8 {
// -- Bits type
// --------- Flags type
const A = 1;
// ----- Flag
}
}
let flag = FlagsType::A;
// ---- Flags value
```
## Known and unknown bits
Any bits in a flag you define are called _known bits_. Any other bits are _unknown bits_.
In the following flags type:
```
# use bitflags::bitflags;
bitflags! {
struct Flags: u8 {
const A = 1;
const B = 1 << 1;
const C = 1 << 2;
}
}
```
The known bits are `0b0000_0111` and the unknown bits are `0b1111_1000`.
`bitflags` doesn't guarantee that a flags value will only ever have known bits set, but some operators
will unset any unknown bits they encounter. In a future version of `bitflags`, all operators will
unset unknown bits.
If you're using `bitflags` for flags types defined externally, such as from C, you probably want all
bits to be considered known, in case that external source changes. You can do this using an unnamed
flag, as described in [externally defined flags](#externally-defined-flags).
## Zero-bit flags
Flags with no bits set should be avoided because they interact strangely with [`Flags::contains`]
and [`Flags::intersects`]. A zero-bit flag is always contained, but is never intersected. The
names of zero-bit flags can be parsed, but are never formatted.
## Multi-bit flags
Flags that set multiple bits should be avoided unless each bit is also in a single-bit flag.
Take the following flags type as an example:
```
# use bitflags::bitflags;
bitflags! {
struct Flags: u8 {
const A = 1;
const B = 1 | 1 << 1;
}
}
```
The result of `Flags::A ^ Flags::B` is `0b0000_0010`, which doesn't correspond to either
`Flags::A` or `Flags::B` even though it's still a known bit.
Á � �
Yield the bits of a source flags value in a set of contained flags values.
Á �
An iterator over flags values.
This iterator will yield flags values for contained, defined flags first, with any remaining bits yielded
as a final flags value.
Á
� � ’ � 3
ˆ � � ˈXêE> �
’
An iterator over flags values.
This iterator only yields flags values for contained, defined, named flags. Any remaining bits
won't be yielded, but can be found with the [`IterNames::remaining`] method.
Á � � � Ô±ël–ÏS �
‚
‘ � � ˈXêE>
An iterator over all defined named flags.
This iterator will yield flags values for all defined named flags, regardless of
whether they are contained in a particular flags value.
Á
� $ � � ˈXêE>
Parsing flags from text.
Format and parse a flags value as text using the following grammar:
- _Flags:_ (_Whitespace_ _Flag_ _Whitespace_)`|`*
- _Flag:_ _Name_ | _Hex Number_
- _Name:_ The name of any defined flag
- _Hex Number_: `0x`([0-9a-fA-F])*
- _Whitespace_: (\s)*
As an example, this is how `Flags::A | Flags::B | 0x0c` can be represented as text:
```text
A | B | 0x0c
```
Alternatively, it could be represented without whitespace:
```text
A|B|0x0C
```
Note that identifiers are *case-sensitive*, so the following is *not equivalent*:
```text
a|b|0x0C
```
Á ‹ ‘ �
Write a flags value as text.
Any bits that aren't part of a contained flag will be formatted as a hex number.
ÁL� ¸ � ‹
�
Parse a flags value from text.
This function will fail on any names that don't correspond to defined flags.
Unknown bits will be retained.
ÁD»
– –
Write a flags value as text, ignoring any unknown bits.
Á”Ž � ¦
Parse a flags value from text.
This function will fail on any names that don't correspond to defined flags.
Unknown bits will be ignored.
ÁŒÛ
Write only the contained, defined, named flags in a flags value as text.
Á„Ò
Parse a flags value from text.
This function will fail on any names that don't correspond to defined flags.
This function will fail to parse hex values.
Á|È$
–
Encode a value as a hex string.
Implementors of this trait should not write the `0x` prefix.
Á
Parse a value from a hex string.
Á
� 4
� ; ˜ ‘ ˜
Define a flag.
If `name` is non-empty then the flag is named, otherwise it's unnamed.
Á
Get the name of this flag.
If the flag is unnamed then the returned string will be empty.
Á$÷
Get the flags value of this flag.
Á,ô
Whether the flag is named.
If [`Flag::name`] returns a non-empty string then this method will return `true`.
ÁDº
Whether the flag is unnamed.
If [`Flag::name`] returns a non-empty string then this method will return `false`.
ÁT’ �
A set of defined flags using a bits type as storage.
## Implementing `Flags`
This trait is implemented by the [`bitflags`](macro.bitflags.html) macro:
```
use bitflags::bitflags;
bitflags! {
struct MyFlags: u8 {
const A = 1;
const B = 1 << 1;
}
}
```
It can also be implemented manually:
```
use bitflags::{Flag, Flags};
struct MyFlags(u8);
impl Flags for MyFlags {
const FLAGS: &'static [Flag<Self>] = &[
Flag::new("A", MyFlags(1)),
Flag::new("B", MyFlags(1 << 1)),
];
type Bits = u8;
fn from_bits_retain(bits: Self::Bits) -> Self {
MyFlags(bits)
}
fn bits(&self) -> Self::Bits {
self.0
}
}
```
## Using `Flags`
The `Flags` trait can be used generically to work with any flags types. In this example,
we can count the number of defined named flags:
```
# use bitflags::{bitflags, Flags};
fn defined_flags<F: Flags>() -> usize {
F::FLAGS.iter().filter(|f| f.is_named()).count()
}
bitflags! {
struct MyFlags: u8 {
const A = 1;
const B = 1 << 1;
const C = 1 << 2;
const _ = !0;
}
}
assert_eq!(3, defined_flags::<MyFlags>());
```
Á � ‚ ‹ � � ‚ � � �
ˆ
�
�
� � ˈXêE>
$¯
�
� Ô±ël–ÏS
� –
�
� 0+
� 3` ‚
ˆ � ;
� A
�
A bits type that can be used as storage for a flags type.
Á
� F � F � � � � � � � � � � � � � � � �
� J � J ´
� K ˜ › � K ¸
� L ˜ ¸
� M ˆ ‹ � M ‘
˜ ›
� Œ
ˆ ‘ ›
’ ˜ ¸ ˜ � Q
– › � R
›
ˆ � � � � � � � � � – ˆ ˜ ˜ � Z � ] � ] ‘
Generate a flags type.
# `struct` mode
A declaration that begins with `$vis struct` will generate a `struct` for a flags type, along with
methods and trait implementations for it. The body of the declaration defines flags as constants,
where each constant is a flags value of the generated flags type.
## Examples
Generate a flags type using `u8` as the bits type:
```
# use bitflags::bitflags;
bitflags! {
struct Flags: u8 {
const A = 1;
const B = 1 << 1;
const C = 0b0000_0100;
}
}
```
Flags types are private by default and accept standard visibility modifiers. Flags themselves
are always public:
```
# use bitflags::bitflags;
bitflags! {
pub struct Flags: u8 {
// Constants are always `pub`
const A = 1;
}
}
```
Flags may refer to other flags using their [`Flags::bits`] value:
```
# use bitflags::bitflags;
bitflags! {
struct Flags: u8 {
const A = 1;
const B = 1 << 1;
const AB = Flags::A.bits() | Flags::B.bits();
}
}
```
A single `bitflags` invocation may include zero or more flags type declarations:
```
# use bitflags::bitflags;
bitflags! {}
bitflags! {
struct Flags1: u8 {
const A = 1;
}
struct Flags2: u8 {
const A = 1;
}
}
```
# `impl` mode
A declaration that begins with `impl` will only generate methods and trait implementations for the
`struct` defined outside of the `bitflags` macro.
The struct itself must be a newtype using the bits type as its field.
The syntax for `impl` mode is identical to `struct` mode besides the starting token.
## Examples
Implement flags methods and traits for a custom flags type using `u8` as its underlying bits type:
```
# use bitflags::bitflags;
struct Flags(u8);
bitflags! {
impl Flags: u8 {
const A = 1;
const B = 1 << 1;
const C = 0b0000_0100;
}
}
```
# Named and unnamed flags
Constants in the body of a declaration are flags. The identifier of the constant is the name of
the flag. If the identifier is `_`, then the flag is unnamed. Unnamed flags don't appear in the
generated API, but affect how bits are truncated.
## Examples
Adding an unnamed flag that makes all bits known:
```
# use bitflags::bitflags;
bitflags! {
struct Flags: u8 {
const A = 1;
const B = 1 << 1;
const _ = !0;
}
}
```
Flags types may define multiple unnamed flags:
```
# use bitflags::bitflags;
bitflags! {
struct Flags: u8 {
const _ = 1;
const _ = 1 << 1;
}
}
```
Á � ` � b
‚ ‘ � a � a – � ›
� ˜
�
� s ‚ � c ¸
’ ˆ � e ‘
‘ ´
˜
� f
unused_mutÁ � h ’ ¸ ¸ × � l ‚ ‹ –
‘
˜
’ ˜ ˆ ˜ › ‘
˜ � � q ‹ � r
� s –
× – ‘ ‚ ‹ � t � ‘
´ � ¸ ˜
�
‘
ˆ ˜
’ ´
‹ –
× ‘
‹ � { ’ ˜ ˜
‚
� � � ‘ � ’ � – � � � � � � � � �
� � � � ¸ � � � � � � ˜ � � � � � � � � � � � � �
�
� � � � ‚ � ‚
empty_bodyÁ
� … � …
is_empty_bodyÁ � † � †
contains_bodyÁ � ‡ � ˆ � ˆ � ‰
union_bodyÁ � Š
� Œ � Œ � � � � � � � � � Ž � � � � � � � � � � � � � � � � � � � � � � � • � •
� ™ � š � ë � › � ì � � � � × � � � � � � ž � � � � � � � � � ¤ � ¥
� §
� © ’ � � � ¬
� ® � ý
```ignoreÁ � » � ¿ �
� Á � Á � Á
� � Ã
� Ã � � Ã � µ
� µ �
�
� µ
� Æ � Ç � Ç
� µ �
� µ � È � Ï �
� Ð � Ñ � Ñ
� Ô �
2026-01-27 22:27:17 +00:00
attrs_restÁ �
2026-01-24 22:59:20 +00:00
�
� Ø
� Ü �
�
� � Ü
� Ý
� à �
� á
� á � â � â
�
� ã �
� ä �
� ä �
2026-01-27 22:27:17 +00:00
2026-01-24 22:59:20 +00:00
�
× ‹
× � ‘ ¸
2026-01-27 22:27:17 +00:00
2026-01-24 22:59:20 +00:00
� � � ’
�
�
’
×
2026-01-27 22:27:17 +00:00
2026-01-24 22:59:20 +00:00
� ‚ � ´ � ‚
�
�
›
‘
–
2026-01-27 22:27:17 +00:00
2026-01-24 22:59:20 +00:00
×
2026-01-27 22:27:17 +00:00
2026-01-24 22:59:20 +00:00
ˆ � �
›
� ‚ � � › � � × � ˆ ‘ � � � ‹ � � � � � � � E ’
× � # ‘ ¸ �
× � ˜
‚ ¸
2026-01-27 22:27:17 +00:00
˜ � $
2026-01-24 22:59:20 +00:00
ˆ – × × ˆ � & � ' ‚ ‘ ‹ ’ � '
– ´ × � � ‹ � ( ˜ � ( – › � ( � �
‹ � * � � * � + � + � � � , ’
´ � � - › ´ ‚ ˜ ´ ¸
� 1 ‘
× ‚ ¸ � ˆ � 4 ›
’
– ¸ × � 7 ’ � 7 ¸ ‚ × ‹ � : ’ ´ × ‚ � ; � ; ‹ � <
´ ¸
› ‚
˜ ‘ ‹ ˜ � ? ˜ × � @ › � A ˜ › � A � B ˆ ˆ � D � D ‹ � EB ›
× ˆ ’ ‘ ‹
� G � HV × › � J › ´ � L � � ˜ ´ ‚ ˆ � O › � P � P � › � ‚ ‘
‹ � R – ˜
‘ × ’ ˜ ¸ ˜ � T? ´ ¸
2026-01-27 22:27:17 +00:00
2026-01-24 22:59:20 +00:00
� V
‹ � W ’ ˜ ‘ � X � X ¸ ‘ × ˆ � Y ‚
˜ ´
� Z � Z ‘ – › � Z × ‘ � [ ’ – ˜ ‘ � \ ‚
‹ › ¸
’ – › ¸ ‹ ‘ � ^ › � ^ × ‘ ˆ ’ ‘ ‹
� _
× ˆ › � ` � a ‘ � a ¸ ‘ � b � b ‘ ’
›
‚ × ’ � d ¸
‚ � e � e ˜
2026-01-27 22:27:17 +00:00
� f – � f ´ – � g ˜
2026-01-24 22:59:20 +00:00
´
