1 //===-- llvm/ADT/BitmaskEnum.h ----------------------------------*- C++ -*-===//
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7 //===----------------------------------------------------------------------===//
9 #ifndef LLVM_ADT_BITMASKENUM_H
10 #define LLVM_ADT_BITMASKENUM_H
13 #include <type_traits>
16 #include "llvm/Support/MathExtras.h"
18 /// LLVM_MARK_AS_BITMASK_ENUM lets you opt in an individual enum type so you can
19 /// perform bitwise operations on it without putting static_cast everywhere.
23 /// E1 = 1, E2 = 2, E3 = 4, E4 = 8,
24 /// LLVM_MARK_AS_BITMASK_ENUM(/* LargestValue = */ E4)
28 /// MyEnum A = (E1 | E2) & E3 ^ ~E4; // Look, ma: No static_cast!
32 /// Normally when you do a bitwise operation on an enum value, you get back an
33 /// instance of the underlying type (e.g. int). But using this macro, bitwise
34 /// ops on your enum will return you back instances of the enum. This is
35 /// particularly useful for enums which represent a combination of flags.
37 /// The parameter to LLVM_MARK_AS_BITMASK_ENUM should be the largest individual
38 /// value in your enum.
40 /// All of the enum's values must be non-negative.
41 #define LLVM_MARK_AS_BITMASK_ENUM(LargestValue) \
42 LLVM_BITMASK_LARGEST_ENUMERATOR = LargestValue
44 /// LLVM_ENABLE_BITMASK_ENUMS_IN_NAMESPACE() pulls the operator overloads used
45 /// by LLVM_MARK_AS_BITMASK_ENUM into the current namespace.
47 /// Suppose you have an enum foo::bar::MyEnum. Before using
48 /// LLVM_MARK_AS_BITMASK_ENUM on MyEnum, you must put
49 /// LLVM_ENABLE_BITMASK_ENUMS_IN_NAMESPACE() somewhere inside namespace foo or
50 /// namespace foo::bar. This allows the relevant operator overloads to be found
53 /// You don't need to use this macro in namespace llvm; it's done at the bottom
55 #define LLVM_ENABLE_BITMASK_ENUMS_IN_NAMESPACE() \
56 using ::llvm::BitmaskEnumDetail::operator~; \
57 using ::llvm::BitmaskEnumDetail::operator|; \
58 using ::llvm::BitmaskEnumDetail::operator&; \
59 using ::llvm::BitmaskEnumDetail::operator^; \
60 using ::llvm::BitmaskEnumDetail::operator|=; \
61 using ::llvm::BitmaskEnumDetail::operator&=; \
62 /* Force a semicolon at the end of this macro. */ \
63 using ::llvm::BitmaskEnumDetail::operator^=
67 /// Traits class to determine whether an enum has a
68 /// LLVM_BITMASK_LARGEST_ENUMERATOR enumerator.
69 template <typename E, typename Enable = void>
70 struct is_bitmask_enum : std::false_type {};
73 struct is_bitmask_enum<
74 E, std::enable_if_t<sizeof(E::LLVM_BITMASK_LARGEST_ENUMERATOR) >= 0>>
76 namespace BitmaskEnumDetail {
78 /// Get a bitmask with 1s in all places up to the high-order bit of E's largest
80 template <typename E> std::underlying_type_t<E> Mask() {
81 // On overflow, NextPowerOf2 returns zero with the type uint64_t, so
82 // subtracting 1 gives us the mask with all bits set, like we want.
83 return NextPowerOf2(static_cast<std::underlying_type_t<E>>(
84 E::LLVM_BITMASK_LARGEST_ENUMERATOR)) -
88 /// Check that Val is in range for E, and return Val cast to E's underlying
90 template <typename E> std::underlying_type_t<E> Underlying(E Val) {
91 auto U = static_cast<std::underlying_type_t<E>>(Val);
92 assert(U >= 0 && "Negative enum values are not allowed.");
93 assert(U <= Mask<E>() && "Enum value too large (or largest val too small?)");
97 constexpr unsigned bitWidth(uint64_t Value) {
98 return Value ? 1 + bitWidth(Value >> 1) : 0;
101 template <typename E, typename = std::enable_if_t<is_bitmask_enum<E>::value>>
103 return static_cast<E>(~Underlying(Val) & Mask<E>());
106 template <typename E, typename = std::enable_if_t<is_bitmask_enum<E>::value>>
107 E operator|(E LHS, E RHS) {
108 return static_cast<E>(Underlying(LHS) | Underlying(RHS));
111 template <typename E, typename = std::enable_if_t<is_bitmask_enum<E>::value>>
112 E operator&(E LHS, E RHS) {
113 return static_cast<E>(Underlying(LHS) & Underlying(RHS));
116 template <typename E, typename = std::enable_if_t<is_bitmask_enum<E>::value>>
117 E operator^(E LHS, E RHS) {
118 return static_cast<E>(Underlying(LHS) ^ Underlying(RHS));
121 // |=, &=, and ^= return a reference to LHS, to match the behavior of the
122 // operators on builtin types.
124 template <typename E, typename = std::enable_if_t<is_bitmask_enum<E>::value>>
125 E &operator|=(E &LHS, E RHS) {
130 template <typename E, typename = std::enable_if_t<is_bitmask_enum<E>::value>>
131 E &operator&=(E &LHS, E RHS) {
136 template <typename E, typename = std::enable_if_t<is_bitmask_enum<E>::value>>
137 E &operator^=(E &LHS, E RHS) {
142 } // namespace BitmaskEnumDetail
144 // Enable bitmask enums in namespace ::llvm and all nested namespaces.
145 LLVM_ENABLE_BITMASK_ENUMS_IN_NAMESPACE();
146 template <typename E, typename = std::enable_if_t<is_bitmask_enum<E>::value>>
147 constexpr unsigned BitWidth = BitmaskEnumDetail::bitWidth(uint64_t{
148 static_cast<std::underlying_type_t<E>>(
149 E::LLVM_BITMASK_LARGEST_ENUMERATOR)});