I recently looked at P4313R1, a standards proposal paper which adds a set of bitmask operations for enums, using a C++26 annotation to opt-in. The core idea being that, to use an example from the paper, given code like the below:
\nenum class [[=std::bitmask_type]] Permission {\n None = 0,\n Read = 1 << 0,\n Write = 1 << 1,\n Execute = 1 << 2,\n};The [[=std::bitmask_type]] annotation would automatically imbue Permission with an accessible set of bitwise operations so that you as a user needn’t write them out yourself. This got me thinking about the murky underbelly of C++ integer operations. Your C++ compiler will happily compute bitwise operations for any integral type as a builtin operation. This extends to types which we don’t traditionally think of as integers, such as wchar_t, the UTF character types char8_t through char32_t, and bool. But slightly more happens here than meets the eye. Because when you attempt to perform an operation like a | b, and the type of a and b is an integral type smaller than int, the language does not operate on the bit patterns of a and b directly. They undergo integral promotion - they are promoted up to int as an intermediate state, the bit patterns of these two ints are combined, and the result is returned to you, still as an int.<sup>1</sup> Consider the below:
//Two shorts\nconstexpr short perm_A {1 << 0};\nconstexpr short perm_B {1 << 1};\n//And the result type of running a bitwise operation on them is int\nstatic_assert(std::same_as<decltype(perm_A | perm_B), int>);Now, for the most part this is harmless - if you cast the above perm_A | perm_B back to short then the unnecessary bytes are truncated away and you’re left with a short which contains exactly the value it would have held if you’d combined perm_A and perm_B as short directly. And if you want to be certain that you are keeping your types consistent, and avoid the pernicious bugs of silent narrowing conversions, you can get into the habit of static_cast-ing the result of your bitwise operation to its original type. The important thing here however is that integral promotion is not optional. Unlike most other areas of C++ the developer doesn’t get a choice - your types will unavoidably be promoted for these operations.
The second part of what makes this a hazard for bool specifically is boolean conversion, a special case which does not truncate but instead explicitly converts zero to false and non-zero values to true. For these non-zero values, whatever bit pattern was previously stored is discarded and replaced with true, which has an integer value of 1. So if we take code like this:
int x{10};\nbool b{static_cast<bool>(x)};and look at the generated asm (in this case from unoptimised x86-64 gcc 16.2):
\nmov DWORD PTR [rbp-4], 10 ;Store the value of 10\ncmp DWORD PTR [rbp-4], 0 ;Then compare to 0, set ZF if x is zero\nsetne al ;Write 1 to AL if ZF is clear\nmov BYTE PTR [rbp-5], al ;Store the resultThe standard (specifically [conv.bool]) bases converting to bool on the only possible values which bool can hold - true and false, regardless of whatever bit pattern may have originally been used to create them.
With all of that covered, let’s talk through what happens when you try to evaluate ~true and then cast the result to a bool:
true is promoted to anint with a value of1 .1 as anint is calculated as-2 , as two’s complement behaviour is required as of C++20.-2 is then cast back down tobool , undergoes boolean conversion, and since-2 is non-zero, becomestrue .There you have it, the complement of true is true, or spelled in C++ static_cast<bool>(~true) == true.
This brings us back to enums. An enum is permitted to use any integral type as its underlying type, including our good friend bool. So let’s define one:
enum class [[=std::bitmask_type]] boolean : bool{\n FALSE,\n TRUE,\n};Let’s also look at the bitwise complement operator as laid out in P4313R1:
\ntemplate<bitmask-like T> constexpr T operator~ (T lhs) noexcept {\n return static_cast<T>(~to_underlying(lhs));\n}By now the workings of that operator should be a familiar shape - first we convert the enum to its underlying type (in our case bool), then integral promotion is applied if that type is lower ranked than int, then we perform the bitwise operation, then we cast back to the enum type. As we would expect:
static_assert(~boolean::TRUE == boolean::TRUE);Godbolt here.
\nThis has all the potential to be a slightly confusing corner case in the language.
\nThere is one exceptional case here which compounds the problem. If we try to run that same example in gcc, we get a different result:
\nstatic_assert(~boolean::TRUE == boolean::FALSE);Godbolt here.
\nSo what is going on with gcc? If we move the operation to runtime by defining two functions which depend on it as a runtime value:
\nenum class boolean : bool{\n FALSE,\n TRUE,\n};\nvoid f(int x, bool& out) {\n out = static_cast<bool>(x);\n}\nvoid g(int x, boolean& out) {\n out = static_cast<boolean>(x);\n}and look at the asm (again unoptimised x86-64), then we get:
\n"f(int, bool&)":\n push rbp\n mov rbp, rsp\n mov DWORD PTR [rbp-4], edi\n mov QWORD PTR [rbp-16], rsi\n cmp DWORD PTR [rbp-4], 0\n setne dl ;same setne pattern from [conv.bool] earlier\n mov rax, QWORD PTR [rbp-16]\n mov BYTE PTR [rax], dl\n nop\n pop rbp\n ret\n"g(int, boolean&)":\n push rbp\n mov rbp, rsp\n mov DWORD PTR [rbp-4], edi\n mov QWORD PTR [rbp-16], rsi\n mov eax, DWORD PTR [rbp-4]\n and eax, 1 ;store the low bit in eax\n mov rdx, QWORD PTR [rbp-16]\n mov BYTE PTR [rdx], al ;and move al to the out-param\n nop\n pop rbp\n retWhat we see is that when the type is not spelled bool, gcc will truncate down to the lowest bit rather than perform a boolean conversion. Any even value, when cast down, will produce boolean::FALSE, and any odd one will produce boolean::TRUE.
This is unique to enum types specifically, gcc generally performs consistently when handling bool directly:
constexpr boolean b{boolean::TRUE};\nstatic_assert(static_cast<bool>(~b) == false);\nstatic_assert(static_cast<bool>(~true) == true);\nstatic_assert(std::to_underlying(~b) == false);\nstatic_assert(static_cast<bool>(~std::to_underlying(b)) == true);In contrast, Clang and MSVC will evaluate the result of all four of these complement-and-cast combinations as true, which is what the standard says they must be. Full godbolt comparison here. This seems to be a fairly long-lived conformance bug in gcc.
But there is one place in the standard where integral promotion rules go further and introduce a new vector for undefined behaviour to enter into your program when doing these bitmask operations. Consider this code:
\nenum nums{\n zero,\n one,\n two,\n three,\n};\n//This is implementation defined but holds on gcc and Clang.\nstatic_assert(std::is_same_v<std::underlying_type_t<nums>, unsigned int>);\n//nums uses an unsigned int as its base, therefore the entire domain of representable values is >= 0.\n//So let's test this:\nstatic_assert(~one >= 0); //FAILSGodbolt here
\nLooking at the diagnostic, gcc gives us:
\n<source>:15:20: error: static assertion failed\n 15 | static_assert(~one >= 0); //FAILS\n | ~~~~~^~~~\n • the comparison reduces to '(-2 >= 0)'So what happened here? Well, the passage in the standard which covers integral promotion, [conv.prom], carves out a special bullet for unscoped enumeration types with no fixed underlying type to behave differently from integer types when promoting. If the entire range of values can be stored in an int, then that is the type which it promotes to, then it tries unsigned int, and if that fails it repeats this signed-then-unsigned pattern for long and long long until it finds a suitable type. But, where this differs from plain integer types is that it only considers the effective range of representable values; and so an enum backed by unsigned int will promote to int regardless of the normal conversion ranking which would forbid it for integral types. As before, the fact that you are calling the builtin operator via ~one will unavoidably promote it to int, its complement is calculated as -2, and then the comparison is performed between two ints, and fails. If instead you convert to the underlying type first then you really see the asymmetry - static_assert(~std::to_underlying(one) >= 0); succeeds, and is so vacuously true that gcc even warns about its redundancy.
But this is only half the battle, and we need to talk about converting the result of our bitwise operation back to the enum type, and this is where UB creeps in. An unscoped enum with no specified underlying type defines itself in terms of a valid range of values determined by its enumerators independently of the range of whatever actual type is used by the compiler to back it. [dcl.enum] tells us the value range of such an enum is the value range of a hypothetical integer type of width M, where M is the minimum bits required to represent all enumerators. To demonstrate, consider a few examples:
\nenum small{ //Range of enumerators is 0..1, so value range is that of an unsigned, one-bit integer.\n a = 0,\n b = 1,\n};\nenum medium{ //Range of enumerators is 0..7, so value range is that of an unsigned, three-bit integer\n c = 0,\n d = 4,\n e = 7\n};\nenum large{ //Range of enumerators is -1..100, so value range is that of a signed, eight-bit integer\n f = -1,\n g = 10,\n h = 100,\n};Even though your compiler will quite likely store these enums as unsigned int and int, only a subset of possible representable values is valid to use - that of the M-width integer. [expr.static.cast] in the standard makes it clear that it is undefined behaviour to cast a value outside of that range to the enum type. So, using the enumerators of the above example:
static_cast<small>(1); //Well-defined\nstatic_cast<small>(2); //UB\nstatic_cast<medium>(3); //Well-defined: while not a value of an enumerator, it is within the range of an unsigned, three-bit integer\nstatic_cast<medium>(8); //UB\nstatic_cast<large>(-128); //Well-defined\nstatic_cast<large>(128); //UBThis is our danger zone. The bitwise operators, in particular operator~, can produce values which are out of the well-defined value range for an enum, and user-defined operators which attempt to cast this value back down to the enum type can invoke UB.
But, I hear you cry, what about the example earlier with ~one? We saw that give a value of -2 which is outside the value range of nums. This is true, but here is where integral promotion actually saves us - one was promoted to int before we calculated its complement, and it was never cast back down again to invoke our UB. We only get into dangerous territory with a user-defined operator which converts the result of the operation back down to the original enum type.
It is also important to note that this UB risk only applies to unscoped “plain” enums with no fixed underlying type. All scoped enum types have a fixed underlying type, even if they don’t specify it (in that case, int); and all unscoped enum types which do specify a fixed underlying type inherit that type’s value range instead of inventing their own.
Let’s say that, like P4313, you are adding bitmask operations to enums for your own code. Now that we have more weirdness in this area of C++, how would you go about making sure that your code is correct and unconfusing? Avoiding the bool case is simple - just constrain away that the underlying type can’t be bool, either for all enums or for the complement operator. But the standard doesn’t come with a handy type trait or reflection metafunction to specifically detect an unscoped enum with no fixed underlying type. Fortunately we can make one:
template<typename E>\nconcept unfixed_enum = std::is_enum_v<E> && !requires { E{0}; };[dcl.init.list] only permits this initialization from a scalar for enums with a fixed underlying type, and 0 is the only possible value which is representable for all possible enums. To cover the edge cases, the standard defines an enum with no enumerators as having the value range of an unsigned, one-bit integer; and the thing which excludes 1 as a possible value is enum E{ a = -1 };, which has a range [-1, 0]. Be sure not to forget the std::is_enum_v. After all, there are many types for which T{0} is ill-formed, and most of them are not enums.
This post has mostly been focused on the bitwise complement operator, but the UB trap of an unfixed enum also applies to the bitwise left shift operator. If you take the route of constraining per operation, don’t let it slip your mind.
\nThis brings us back once again to P4313R1. At time of writing, the concept which constrains these operators only constrains the type to be some enumeration type annotated with [[=std::bitmask_type]]. As such, it will allow confusing behaviour on enum types which are backed by bool, and potential UB on plain enums with no fixed underlying type. If the authors don’t want to standardise the above init-list trick, they could constrain it on std::is_scoped_enum as a conservative approach to prevent users from having easy access to the UB, since all unscoped enums can use the builtin bitwise operators anyway (albeit returning int). They could also constrain the underlying type to not be bool to minimise the confusion; particularly as the diagnostic which would normally get issued for complementing a bool in user code would be suppressed by default if it came from a system header. I do intend to contact the authors of P4313 about this to see if they want to add these constraints to their paper.
You might be wondering how the standard defines conversions of floating point numbers to these bool-backed enums. It is perhaps unsurprising - [expr.static.cast] requires that the behaviour is equivalent to first converting the floating point value to the underlying type of the enum, and then converting it to the enum type; pointing the user to [conv.fpint] which has an explicit note directing readers to our old friend [conv.bool]. Per the standard, this should mean that any floating point value other than exactly 0.0 or -0.0 would convert to boolean::TRUE, otherwise we end up back at boolean::FALSE.
So let’s start small:
\nenum class boolean : bool {\n FALSE,\n TRUE,\n};\nstatic_assert(static_cast<boolean>(0.0) == boolean::FALSE);\nstatic_assert(static_cast<boolean>(0.5) == boolean::TRUE);\nstatic_assert(static_cast<boolean>(2.5) == boolean::TRUE);Godbolt here.
\nBoth Clang and gcc reject this code. The errors are that (boolean)2.5e+0 is not a constant expression; and static_cast<boolean>(0.5) == boolean::TRUE is wrong, and is instead equal to boolean::FALSE. MSVC accepts the above code.
But let’s go further and inspect what actually gets stored there. We write a function to examine the bit pattern generated from these casts, then try some values:
\nvoid show(double d) {\n const boolean e = static_cast<boolean>(d);\n unsigned char byte {};\n std::memcpy(&byte, &e, 1);\n std::println("static_cast<boolean>({:7.1f}) stored byte {:3} required {}",\n d, byte, (d != 0.0) ? 1 : 0);\n}\nint main() {\n show(0.0);\n show(0.5);\n show(1.0);\n show(2.5);\n show(3.0);\n show(256.0);\n show(-2.5);\n}Godbolt here.
\nThe above code compiles without warning on all three compilers, but while MSVC again does the right thing in all cases, gcc and Clang’s behaviour is much more worrisome. Looking at the output, we see that gcc will always just truncate the value to an integer, then load that bit pattern into the resulting boolean. So 2.5 truncates to 2 and gives a boolean whose underlying bit pattern is 2. Clang does the same thing on unoptimised builds, but when optimisation is turned on, the truncated value then goes through the [conv.bool] transformation as normal and produces the right answer for all non-zero values outside of the range (-1, 1).
This is more concerning than some funky bit patterns, however. The valid range of boolean is [0, 1]. It is UB to read objects with bit patterns outside of this range. But, I hear you ask, what happens if we take these booleans and cast them back to bool, triggering a boolean conversion with no initial floating point state? MSVC again does the right thing; gcc doesn’t modify the bit patterns, leaving us with bool which are out of range of the type (and therefore UB to read); and Clang is where the fun happens again. Running the above code with a cast from e to a bool, and then memcpy-ing that bool into the unsigned char, we get this result for unoptimised builds:
| 0.0 | 0.5 | 1.0 | 2.5 | 3.0 | 256.0 | -2.5 | |
|---|---|---|---|---|---|---|---|
| required | 0 | 1 | 1 | 1 | 1 | 1 | 1 |
| gcc 14 / 15 / 16 | 0 | 0 | 1 | 2 | 3 | 0 | 254 |
| clang 19 / 20 / 21 | 0 | 0 | 1 | 0 | 1 | 0 | 0 |
| clang 23.1.1 | 0 | 0 | 1 | 1 | 1 | 0 | 1 |
Versions of Clang before 23 appear to simply perform trunc(d) & 1; meaning that after truncation, odd numbers are true and even numbers are false. Clang 23 performs (trunc(d) % 256) != 0, narrowing to a byte first. So 256.0 becomes FALSE and 257.0 becomes TRUE. Optimised builds act as before - truncating then doing the proper boolean conversion.
Ultimately this all comes to a rather absurd head. Consider the below code:
\n#include <print>\nenum class boolean : bool {\n FALSE,\n TRUE,\n};\n//Force this to be runtime\nboolean make(double d) {\n return static_cast<boolean>(d);\n}\nint main() {\n const boolean e = make(2.5);\n std::println("e == boolean::TRUE : {}", e == boolean::TRUE);\n std::println("e == boolean::FALSE : {}", e == boolean::FALSE);\n const bool b = static_cast<bool>(e);\n std::println("b == true : {}", b == true);\n std::println("b == false : {}", b == false);\n std::println("b + 0 : {}", b + 0);\n}Godbolt here.
\nMSVC again leads the pack in giving the correct answer. Clang gets it exactly wrong and thinks that e is FALSE and b is false. gcc takes things up a notch, by providing an instance of an enum which compares equal to all of its enumerators, and a bool which is neither true nor false, until you turn on the optimiser and get a bool which is both true and false.
And to hit all the obligatory targets of any conversation on floating point, infinity and NaN show as 0 and become FALSE as boolean and so cast to false as bool on gcc and Clang; and give 1 and therefore TRUE and true on MSVC.
In lighter news, Clang trunk seems to have fixed the above example to behave correctly, so some of the issues described in this section should be patched out soon.
\nWhat did we learn from all this? Perhaps that even sensible and uncontentious pure-library-level papers such as P4313 should be on their guard against a footgun from some exotic C++ edge case. Or perhaps, in more practical terms:
\nint , there’s a good chance it became anint right under your nose.bool is alwaystrue , even when wrapped in an enum. However you should not rely on this behaviour as gcc has a longstanding bug which gets this wrong (or right, if you prefer logic to C++).int ”. For an integer type of lower conversion rank (not size) thanint , if all values of that type can be represented asint thenint is chosen. Otherwiseunsigned int is chosen. In practice this will usually come out asint ; but on implementations whereint andshort are the same size,unsigned short will promote directly tounsigned int . And for other types such as the charN_t family, conversion can proceed to longer integer types such aslong andlong long .bool is singled out as a special case and always promotes toint . ↩︎