| 1 |
.. title:: clang-tidy - bugprone-suspicious-enum-usage |
| 2 |
|
| 3 |
bugprone-suspicious-enum-usage |
| 4 |
============================== |
| 5 |
|
| 6 |
The checker detects various cases when an enum is probably misused (as a bitmask |
| 7 |
). |
| 8 |
|
| 9 |
1. When "ADD" or "bitwise OR" is used between two enum which come from different |
| 10 |
types and these types value ranges are not disjoint. |
| 11 |
|
| 12 |
The following cases will be investigated only using :option:`StrictMode`. We |
| 13 |
regard the enum as a (suspicious) |
| 14 |
bitmask if the three conditions below are true at the same time: |
| 15 |
|
| 16 |
* at most half of the elements of the enum are non pow-of-2 numbers (because of |
| 17 |
short enumerations) |
| 18 |
* there is another non pow-of-2 number than the enum constant representing all |
| 19 |
choices (the result "bitwise OR" operation of all enum elements) |
| 20 |
* enum type variable/enumconstant is used as an argument of a `+` or "bitwise OR |
| 21 |
" operator |
| 22 |
|
| 23 |
So whenever the non pow-of-2 element is used as a bitmask element we diagnose a |
| 24 |
misuse and give a warning. |
| 25 |
|
| 26 |
2. Investigating the right hand side of `+=` and `|=` operator. |
| 27 |
3. Check only the enum value side of a `|` and `+` operator if one of them is not |
| 28 |
enum val. |
| 29 |
4. Check both side of `|` or `+` operator where the enum values are from the |
| 30 |
same enum type. |
| 31 |
|
| 32 |
Examples: |
| 33 |
|
| 34 |
.. code-block:: c++ |
| 35 |
|
| 36 |
enum { A, B, C }; |
| 37 |
enum { D, E, F = 5 }; |
| 38 |
enum { G = 10, H = 11, I = 12 }; |
| 39 |
|
| 40 |
unsigned flag; |
| 41 |
flag = |
| 42 |
A | |
| 43 |
H; // OK, disjoint value intervals in the enum types ->probably good use. |
| 44 |
flag = B | F; // Warning, have common values so they are probably misused. |
| 45 |
|
| 46 |
// Case 2: |
| 47 |
enum Bitmask { |
| 48 |
A = 0, |
| 49 |
B = 1, |
| 50 |
C = 2, |
| 51 |
D = 4, |
| 52 |
E = 8, |
| 53 |
F = 16, |
| 54 |
G = 31 // OK, real bitmask. |
| 55 |
}; |
| 56 |
|
| 57 |
enum Almostbitmask { |
| 58 |
AA = 0, |
| 59 |
BB = 1, |
| 60 |
CC = 2, |
| 61 |
DD = 4, |
| 62 |
EE = 8, |
| 63 |
FF = 16, |
| 64 |
GG // Problem, forgot to initialize. |
| 65 |
}; |
| 66 |
|
| 67 |
unsigned flag = 0; |
| 68 |
flag |= E; // OK. |
| 69 |
flag |= |
| 70 |
EE; // Warning at the decl, and note that it was used here as a bitmask. |
| 71 |
|
| 72 |
Options |
| 73 |
------- |
| 74 |
.. option:: StrictMode |
| 75 |
|
| 76 |
Default value: 0. |
| 77 |
When non-null the suspicious bitmask usage will be investigated additionally |
| 78 |
to the different enum usage check. |