1 //===-- llvm/ADT/BitmaskEnum.h ----------------------------------*- C++ -*-===// 2 // 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 6 // 7 //===----------------------------------------------------------------------===// 8 9 #ifndef LLVM_ADT_BITMASKENUM_H 10 #define LLVM_ADT_BITMASKENUM_H 11 12 #include <cassert> 13 #include <type_traits> 14 #include <utility> 15 16 #include "llvm/Support/MathExtras.h" 17 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. 20 /// 21 /// \code 22 /// enum MyEnum { 23 /// E1 = 1, E2 = 2, E3 = 4, E4 = 8, 24 /// LLVM_MARK_AS_BITMASK_ENUM(/* LargestValue = */ E4) 25 /// }; 26 /// 27 /// void Foo() { 28 /// MyEnum A = (E1 | E2) & E3 ^ ~E4; // Look, ma: No static_cast! 29 /// } 30 /// \endcode 31 /// 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. 36 /// 37 /// The parameter to LLVM_MARK_AS_BITMASK_ENUM should be the largest individual 38 /// value in your enum. 39 /// 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 43 44 /// LLVM_ENABLE_BITMASK_ENUMS_IN_NAMESPACE() pulls the operator overloads used 45 /// by LLVM_MARK_AS_BITMASK_ENUM into the current namespace. 46 /// 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 51 /// by ADL. 52 /// 53 /// You don't need to use this macro in namespace llvm; it's done at the bottom 54 /// of this file. 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^= 64 65 namespace llvm { 66 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 {}; 71 72 template <typename E> 73 struct is_bitmask_enum< 74 E, std::enable_if_t<sizeof(E::LLVM_BITMASK_LARGEST_ENUMERATOR) >= 0>> 75 : std::true_type {}; 76 namespace BitmaskEnumDetail { 77 78 /// Get a bitmask with 1s in all places up to the high-order bit of E's largest 79 /// value. 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)) - 85 1; 86 } 87 88 /// Check that Val is in range for E, and return Val cast to E's underlying 89 /// type. 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?)"); 94 return U; 95 } 96 97 constexpr unsigned bitWidth(uint64_t Value) { 98 return Value ? 1 + bitWidth(Value >> 1) : 0; 99 } 100 101 template <typename E, typename = std::enable_if_t<is_bitmask_enum<E>::value>> 102 E operator~(E Val) { 103 return static_cast<E>(~Underlying(Val) & Mask<E>()); 104 } 105 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)); 109 } 110 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)); 114 } 115 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)); 119 } 120 121 // |=, &=, and ^= return a reference to LHS, to match the behavior of the 122 // operators on builtin types. 123 124 template <typename E, typename = std::enable_if_t<is_bitmask_enum<E>::value>> 125 E &operator|=(E &LHS, E RHS) { 126 LHS = LHS | RHS; 127 return LHS; 128 } 129 130 template <typename E, typename = std::enable_if_t<is_bitmask_enum<E>::value>> 131 E &operator&=(E &LHS, E RHS) { 132 LHS = LHS & RHS; 133 return LHS; 134 } 135 136 template <typename E, typename = std::enable_if_t<is_bitmask_enum<E>::value>> 137 E &operator^=(E &LHS, E RHS) { 138 LHS = LHS ^ RHS; 139 return LHS; 140 } 141 142 } // namespace BitmaskEnumDetail 143 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)}); 150 151 } // namespace llvm 152 153 #endif 154