Debian Codegraph @

.cargo/vendor/bitflags/spec.md

raw
1 # Bitflags
2
3 `bitflags` generates flags enums with well-defined semantics and ergonomic end-user APIs.
4
5 You can use `bitflags` to:
6
7 - provide more user-friendly bindings to C APIs where flags may or may not be fully known in advance.
8 - generate efficient options types with string parsing and formatting support.
9
10 You can't use `bitflags` to:
11
12 - 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.
13 - define bitfields. `bitflags` only generates types where set bits denote the presence of some combination of flags.
14
15 ## Definitions
16
17 This section formally defines the terminology and semantics of `bitflags`. It's organized so more fundamental concepts are introduced before those that build on them. It may be helpful to start from the bottom of the section and refer back up to concepts defined earlier.
18
19 Examples use `bitflags` syntax with `u8` as the bits type.
20
21 ### Bits type
22
23 A type that defines a fixed number of bits at specific locations.
24
25 ----
26
27 Bits types are typically fixed-width unsigned integers. For example, `u8` is a bits type that defines 8 bits; bit-0 through bit-7.
28
29 ### Bits value
30
31 An instance of a bits type where each bit may be set (`1`) or unset (`0`).
32
33 ----
34
35 Some examples of bits values for the bits type `u8` are:
36
37 ```rust
38 0b0000_0000
39 0b1111_1111
40 0b1010_0101
41 ```
42
43 #### Equality
44
45 Two bits values are equal if their bits are in the same configuration; set bits in one are set in the other, and unset bits in one are unset in the other.
46
47 #### Operations
48
49 Bits values define the bitwise operators and (`&`), or (`|`), exclusive-or (`^`), and negation (`!`) that apply to each of their bits.
50
51 ### Flag
52
53 A set of bits in a bits type that may have a unique name.
54
55 ----
56
57 Bits are not required to be exclusive to a flag. Bits are not required to be contiguous.
58
59 The following is a flag for `u8` with the name `A` that includes bit-0:
60
61 ```rust
62 const A = 0b0000_0001;
63 ```
64
65 The following is a flag for `u8` with the name `B` that includes bit-0, and bit-5:
66
67 ```rust
68 const B = 0b0010_0001;
69 ```
70
71 #### Named flag
72
73 A flag with a name.
74
75 ----
76
77 The following is a named flag, where the name is `A`:
78
79 ```rust
80 const A = 0b0000_0001;
81 ```
82
83 #### Unnamed flag
84
85 A flag without a name.
86
87 ----
88
89 The following is an unnamed flag:
90
91 ```rust
92 const _ = 0b0000_0001;
93 ```
94
95 #### Zero-bit flag
96
97 A flag with a set of zero bits.
98
99 ----
100
101 The following is a zero-bit flag:
102
103 ```rust
104 const ZERO = 0b0000_0000;
105 ```
106
107 #### Single-bit flag
108
109 A flag with a set of one bit.
110
111 ----
112
113 The following are single-bit flags:
114
115 ```rust
116 const A = 0b0000_0001;
117 const B = 0b0000_0010;
118 ```
119
120 #### Multi-bit flag
121
122 A flag with a set of more than one bit.
123
124 ----
125
126 The following are multi-bit flags:
127
128 ```rust
129 const A = 0b0000_0011;
130 const B = 0b1111_1111;
131 ```
132
133 ### Flags type
134
135 A set of defined flags over a specific bits type.
136
137 #### Known bit
138
139 A bit in any defined flag.
140
141 ----
142
143 In the following flags type:
144
145 ```rust
146 struct Flags {
147 const A = 0b0000_0001;
148 const B = 0b0000_0010;
149 const C = 0b0000_0100;
150 }
151 ```
152
153 the known bits are:
154
155 ```rust
156 0b0000_0111
157 ```
158
159 #### Unknown bit
160
161 A bit not in any defined flag.
162
163 ----
164
165 In the following flags type:
166
167 ```rust
168 struct Flags {
169 const A = 0b0000_0001;
170 const B = 0b0000_0010;
171 const C = 0b0000_0100;
172 }
173 ```
174
175 the unknown bits are:
176
177 ```rust
178 0b1111_1000
179 ```
180
181 ### Flags value
182
183 An instance of a flags type using its specific bits value for storage.
184
185 The flags value of a flag is one where each of its bits is set, and all others are unset.
186
187 #### Contains
188
189 Whether all set bits in a source flags value are also set in a target flags value.
190
191 ----
192
193 Given the flags value:
194
195 ```rust
196 0b0000_0011
197 ```
198
199 the following flags values are contained:
200
201 ```rust
202 0b0000_0000
203 0b0000_0010
204 0b0000_0001
205 0b0000_0011
206 ```
207
208 but the following flags values are not contained:
209
210 ```rust
211 0b0000_1000
212 0b0000_0110
213 ```
214
215 #### Intersects
216
217 Whether any set bits in a source flags value are also set in a target flags value.
218
219 ----
220
221 Given the flags value:
222
223 ```rust
224 0b0000_0011
225 ```
226
227 the following flags intersect:
228
229 ```rust
230 0b0000_0010
231 0b0000_0001
232 0b1111_1111
233 ```
234
235 but the following flags values do not intersect:
236
237 ```rust
238 0b0000_0000
239 0b1111_0000
240 ```
241
242 #### Empty
243
244 Whether all bits in a flags value are unset.
245
246 ----
247
248 The following flags value is empty:
249
250 ```rust
251 0b0000_0000
252 ```
253
254 The following flags values are not empty:
255
256 ```rust
257 0b0000_0001
258 0b0110_0000
259 ```
260
261 #### All
262
263 Whether all defined flags are contained in a flags value.
264
265 ----
266
267 Given a flags type:
268
269 ```rust
270 struct Flags {
271 const A = 0b0000_0001;
272 const B = 0b0000_0010;
273 }
274 ```
275
276 the following flags values all satisfy all:
277
278 ```rust
279 0b0000_0011
280 0b1000_0011
281 0b1111_1111
282 ```
283
284 ### Operations
285
286 Examples in this section all use the given flags type:
287
288 ```rust
289 struct Flags {
290 const A = 0b0000_0001;
291 const B = 0b0000_0010;
292 const C = 0b0000_1100;
293 }
294 ```
295
296 #### Truncate
297
298 Unset all unknown bits in a flags value.
299
300 ----
301
302 Given the flags value:
303
304 ```rust
305 0b1111_1111
306 ```
307
308 the result of truncation will be:
309
310 ```rust
311 0b0000_1111
312 ```
313
314 ----
315
316 Truncating doesn't guarantee that a non-empty result will contain any defined flags. Given the following flags type:
317
318 ```rust
319 struct Flags {
320 const A = 0b0000_0101;
321 }
322 ```
323
324 and the following flags value:
325
326 ```rust
327 0b0000_1110;
328 ```
329
330 The result of truncation will be:
331
332 ```rust
333 0b0000_0100;
334 ```
335
336 which intersects the flag `A`, but doesn't contain it.
337
338 This behavior is possible even when only operating with flags values containing defined flags. Given the following flags type:
339
340 ```rust
341 struct Flags {
342 const A = 0b0000_0101;
343 const B = 0b0000_0001;
344 }
345 ```
346
347 The result of `A ^ B` is `0b0000_0100`, which also doesn't contain any defined flag.
348
349 ----
350
351 If all known bits are in the set of at least one defined single-bit flag, then all operations that produce non-empty results will always contain defined flags.
352
353 #### Union
354
355 The bitwise or (`|`) of the bits in two flags values.
356
357 ----
358
359 The following are examples of the result of unioning flags values:
360
361 ```rust
362 0b0000_0001 | 0b0000_0010 = 0b0000_0011
363 0b0000_0000 | 0b1111_1111 = 0b1111_1111
364 ```
365
366 #### Intersection
367
368 The bitwise and (`&`) of the bits in two flags values.
369
370 ----
371
372 The following are examples of the result of intersecting flags values:
373
374 ```rust
375 0b0000_0001 & 0b0000_0010 = 0b0000_0000
376 0b1111_1100 & 0b1111_0111 = 0b1111_0100
377 0b1111_1111 & 0b1111_1111 = 0b1111_1111
378 ```
379
380 #### Symmetric difference
381
382 The bitwise exclusive-or (`^`) of the bits in two flags values.
383
384 ----
385
386 The following are examples of the symmetric difference between two flags values:
387
388 ```rust
389 0b0000_0001 ^ 0b0000_0010 = 0b0000_0011
390 0b0000_1111 ^ 0b0000_0011 = 0b0000_1100
391 0b1100_0000 ^ 0b0011_0000 = 0b1111_0000
392 ```
393
394 #### Complement
395
396 The bitwise negation (`!`) of the bits in a flags value, truncating the result.
397
398 ----
399
400 The following are examples of the complement of a flags value:
401
402 ```rust
403 !0b0000_0000 = 0b0000_1111
404 !0b0000_1111 = 0b0000_0000
405 !0b1111_1000 = 0b0000_0111
406 ```
407
408 #### Difference
409
410 The bitwise union (`|`) of the bits in one flags value and the bitwise negation (`!`) of the bits in another.
411
412 ----
413
414 This operation is not equivalent to the intersection of one flags value with the complement of another (`&!`).
415 The former will truncate the result, where difference will not.
416
417 ----
418
419 The following are examples of the difference between two flags values:
420
421 ```rust
422 0b0000_0001 & !0b0000_0010 = 0b0000_0001
423 0b0000_1101 & !0b0000_0011 = 0b0000_1100
424 0b1111_1111 & !0b0000_0001 = 0b1111_1110
425 ```
426
427 ### Iteration
428
429 Yield the bits of a source flags value in a set of contained flags values.
430
431 ----
432
433 To be most useful, each yielded flags value should set exactly the bits of a defined flag contained in the source. Any known bits that aren't in the set of any contained flag should be yielded together as a final flags value.
434
435 ----
436
437 Given the following flags type:
438
439 ```rust
440 struct Flags {
441 const A = 0b0000_0001;
442 const B = 0b0000_0010;
443 const AB = 0b0000_0011;
444 }
445 ```
446
447 and the following flags value:
448
449 ```rust
450 0b0000_1111
451 ```
452
453 When iterated it may yield a flags value for `A` and `B`, then a final flag with the unknown bits:
454
455 ```rust
456 0b0000_0001
457 0b0000_0010
458 0b0000_1100
459 ```
460
461 It may also yield a flags value for `AB`, then a final flag with the unknown bits:
462
463 ```rust
464 0b0000_0011
465 0b0000_1100
466 ```
467
468 ----
469
470 Given the following flags type:
471
472 ```rust
473 struct Flags {
474 const A = 0b0000_0011;
475 }
476 ```
477
478 and the following flags value:
479
480 ```rust
481 0b0000_0001
482 ```
483
484 When iterated it will still yield a flags value for the known bit `0b0000_0001` even though it doesn't contain a flag.
485
486 ### Formatting
487
488 Format and parse a flags value as text using the following grammar:
489
490 - _Flags:_ (_Whitespace_ _Flag_ _Whitespace_)`|`*
491 - _Flag:_ _Name_ | _Hex Number_
492 - _Name:_ The name of any defined flag
493 - _Hex Number_: `0x`([0-9a-fA-F])*
494 - _Whitespace_: (\s)*
495
496 Flags values can be formatted as _Flags_ by iterating over them, formatting each yielded flags value as a _Flag_. Any yielded flags value that sets exactly the bits of a defined flag with a name should be formatted as a _Name_. Otherwise it must be formatted as a _Hex Number_.
497
498 Formatting and parsing supports three modes:
499
500 - **Retain**: Formatting and parsing roundtrips exactly the bits of the source flags value. This is the default behavior.
501 - **Truncate**: Flags values are truncated before formatting, and truncated after parsing.
502 - **Strict**: A _Flag_ may only be formatted and parsed as a _Name_. _Hex numbers_ are not allowed. A consequence of this is that unknown bits and any bits that aren't in a contained named flag will be ignored. This is recommended for flags values serialized across API boundaries, like web services.
503
504 Text that is empty or whitespace is an empty flags value.
505
506 ----
507
508 Given the following flags type:
509
510 ```rust
511 struct Flags {
512 const A = 0b0000_0001;
513 const B = 0b0000_0010;
514 const AB = 0b0000_0011;
515 const C = 0b0000_1100;
516 }
517 ```
518
519 The following are examples of how flags values can be formatted using any mode:
520
521 ```rust
522 0b0000_0000 = ""
523 0b0000_0001 = "A"
524 0b0000_0010 = "B"
525 0b0000_0011 = "A | B"
526 0b0000_0011 = "AB"
527 0b0000_1111 = "A | B | C"
528 ```
529
530 Truncate mode will unset any unknown bits:
531
532 ```rust
533 0b1000_0000 = ""
534 0b1111_1111 = "A | B | C"
535 0b0000_1000 = "0x8"
536 ```
537
538 Retain mode will include any unknown bits as a final _Flag_:
539
540 ```rust
541 0b1000_0000 = "0x80"
542 0b1111_1111 = "A | B | C | 0xf0"
543 0b0000_1000 = "0x8"
544 ```
545
546 Strict mode will unset any unknown bits, as well as bits not contained in any defined named flags:
547
548 ```rust
549 0b1000_0000 = ""
550 0b1111_1111 = "A | B | C"
551 0b0000_1000 = ""
552 ```