contrib/llvm-project/llvm/include/llvm/ADT/BitmaskEnum.h

   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