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, typename std::enable_if<sizeof(E::LLVM_BITMASK_LARGEST_ENUMERATOR) >=
  75                                0>::type> : 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> typename std::underlying_type<E>::type 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<typename std::underlying_type<E>::type>(
  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> typename std::underlying_type<E>::type Underlying(E Val) {
  91   auto U = static_cast<typename std::underlying_type<E>::type>(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 template <typename E,
  98           typename = typename std::enable_if<is_bitmask_enum<E>::value>::type>
  99 E operator~(E Val) {
 100   return static_cast<E>(~Underlying(Val) & Mask<E>());
 101 }
 102
 103 template <typename E,
 104           typename = typename std::enable_if<is_bitmask_enum<E>::value>::type>
 105 E operator|(E LHS, E RHS) {
 106   return static_cast<E>(Underlying(LHS) | Underlying(RHS));
 107 }
 108
 109 template <typename E,
 110           typename = typename std::enable_if<is_bitmask_enum<E>::value>::type>
 111 E operator&(E LHS, E RHS) {
 112   return static_cast<E>(Underlying(LHS) & Underlying(RHS));
 113 }
 114
 115 template <typename E,
 116           typename = typename std::enable_if<is_bitmask_enum<E>::value>::type>
 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,
 125           typename = typename std::enable_if<is_bitmask_enum<E>::value>::type>
 126 E &operator|=(E &LHS, E RHS) {
 127   LHS = LHS | RHS;
 128   return LHS;
 129 }
 130
 131 template <typename E,
 132           typename = typename std::enable_if<is_bitmask_enum<E>::value>::type>
 133 E &operator&=(E &LHS, E RHS) {
 134   LHS = LHS & RHS;
 135   return LHS;
 136 }
 137
 138 template <typename E,
 139           typename = typename std::enable_if<is_bitmask_enum<E>::value>::type>
 140 E &operator^=(E &LHS, E RHS) {
 141   LHS = LHS ^ RHS;
 142   return LHS;
 143 }
 144
 145 } // namespace BitmaskEnumDetail
 146
 147 // Enable bitmask enums in namespace ::llvm and all nested namespaces.
 148 LLVM_ENABLE_BITMASK_ENUMS_IN_NAMESPACE();
 149
 150 } // namespace llvm
 151
 152 #endif