gdbsupport/enum-flags.h

   1 /* Copyright (C) 2015-2023 Free Software Foundation, Inc.
   2
   3    This file is part of GDB.
   4
   5    This program is free software; you can redistribute it and/or modify
   6    it under the terms of the GNU General Public License as published by
   7    the Free Software Foundation; either version 3 of the License, or
   8    (at your option) any later version.
   9
  10    This program is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13    GNU General Public License for more details.
  14
  15    You should have received a copy of the GNU General Public License
  16    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  17
  18 #ifndef COMMON_ENUM_FLAGS_H
  19 #define COMMON_ENUM_FLAGS_H
  20
  21 #include "traits.h"
  22
  23 /* Type-safe wrapper for enum flags.  enum flags are enums where the
  24    values are bits that are meant to be ORed together.
  25
  26    This allows writing code like the below, while with raw enums this
  27    would fail to compile without casts to enum type at the assignments
  28    to 'f':
  29
  30     enum some_flag
  31     {
  32        flag_val1 = 1 << 1,
  33        flag_val2 = 1 << 2,
  34        flag_val3 = 1 << 3,
  35        flag_val4 = 1 << 4,
  36     };
  37     DEF_ENUM_FLAGS_TYPE(enum some_flag, some_flags);
  38
  39     some_flags f = flag_val1 | flag_val2;
  40     f |= flag_val3;
  41
  42    It's also possible to assign literal zero to an enum flags variable
  43    (meaning, no flags), dispensing adding an awkward explicit "no
  44    value" value to the enumeration.  For example:
  45
  46     some_flags f = 0;
  47     f |= flag_val3 | flag_val4;
  48
  49    Note that literal integers other than zero fail to compile:
  50
  51     some_flags f = 1; // error
  52 */
  53
  54 #ifdef __cplusplus
  55
  56 /* Use this to mark an enum as flags enum.  It defines FLAGS_TYPE as
  57    enum_flags wrapper class for ENUM, and enables the global operator
  58    overloads for ENUM.  */
  59 #define DEF_ENUM_FLAGS_TYPE(enum_type, flags_type)      \
  60   typedef enum_flags<enum_type> flags_type;             \
  61   void is_enum_flags_enum_type (enum_type *)
  62
  63 /* To enable the global enum_flags operators for enum, declare an
  64    "is_enum_flags_enum_type" overload that has exactly one parameter,
  65    of type a pointer to that enum class.  E.g.,:
  66
  67      void is_enum_flags_enum_type (enum some_flag *);
  68
  69    The function does not need to be defined, only declared.
  70    DEF_ENUM_FLAGS_TYPE declares this.
  71
  72    A function declaration is preferred over a traits type, because the
  73    former allows calling the DEF_ENUM_FLAGS_TYPE macro inside a
  74    namespace to define the corresponding enum flags type in that
  75    namespace.  The compiler finds the corresponding
  76    is_enum_flags_enum_type function via ADL.  */
  77
  78 /* Note that std::underlying_type<enum_type> is not what we want here,
  79    since that returns unsigned int even when the enum decays to signed
  80    int.  */
  81 template<int size, bool sign> class integer_for_size { typedef void type; };
  82 template<> struct integer_for_size<1, 0> { typedef uint8_t type; };
  83 template<> struct integer_for_size<2, 0> { typedef uint16_t type; };
  84 template<> struct integer_for_size<4, 0> { typedef uint32_t type; };
  85 template<> struct integer_for_size<8, 0> { typedef uint64_t type; };
  86 template<> struct integer_for_size<1, 1> { typedef int8_t type; };
  87 template<> struct integer_for_size<2, 1> { typedef int16_t type; };
  88 template<> struct integer_for_size<4, 1> { typedef int32_t type; };
  89 template<> struct integer_for_size<8, 1> { typedef int64_t type; };
  90
  91 template<typename T>
  92 struct enum_underlying_type
  93 {
  94   typedef typename
  95     integer_for_size<sizeof (T), static_cast<bool>(T (-1) < T (0))>::type
  96     type;
  97 };
  98
  99 namespace enum_flags_detail
 100 {
 101
 102 /* Private type used to support initializing flag types with zero:
 103
 104    foo_flags f = 0;
 105
 106    but not other integers:
 107
 108    foo_flags f = 1;
 109
 110    The way this works is that we define an implicit constructor that
 111    takes a pointer to this private type.  Since nothing can
 112    instantiate an object of this type, the only possible pointer to
 113    pass to the constructor is the NULL pointer, or, zero.  */
 114 struct zero_type;
 115
 116 /* gdb::Requires trait helpers.  */
 117 template <typename enum_type>
 118 using EnumIsUnsigned
 119   = std::is_unsigned<typename enum_underlying_type<enum_type>::type>;
 120 template <typename enum_type>
 121 using EnumIsSigned
 122   = std::is_signed<typename enum_underlying_type<enum_type>::type>;
 123
 124 }
 125
 126 template <typename E>
 127 class enum_flags
 128 {
 129 public:
 130   typedef E enum_type;
 131   typedef typename enum_underlying_type<enum_type>::type underlying_type;
 132
 133   /* For to_string.  Maps one enumerator of E to a string.  */
 134   struct string_mapping
 135   {
 136     E flag;
 137     const char *str;
 138   };
 139
 140   /* Convenience for to_string implementations, to build a
 141      string_mapping array.  */
 142 #define MAP_ENUM_FLAG(ENUM_FLAG) { ENUM_FLAG, #ENUM_FLAG }
 143
 144 public:
 145   /* Allow default construction.  */
 146   constexpr enum_flags ()
 147     : m_enum_value ((enum_type) 0)
 148   {}
 149
 150   /* The default move/copy ctor/assignment do the right thing.  */
 151
 152   /* If you get an error saying these two overloads are ambiguous,
 153      then you tried to mix values of different enum types.  */
 154   constexpr enum_flags (enum_type e)
 155     : m_enum_value (e)
 156   {}
 157   constexpr enum_flags (enum_flags_detail::zero_type *zero)
 158     : m_enum_value ((enum_type) 0)
 159   {}
 160
 161   enum_flags &operator&= (enum_flags e) &
 162   {
 163     m_enum_value = (enum_type) (m_enum_value & e.m_enum_value);
 164     return *this;
 165   }
 166   enum_flags &operator|= (enum_flags e) &
 167   {
 168     m_enum_value = (enum_type) (m_enum_value | e.m_enum_value);
 169     return *this;
 170   }
 171   enum_flags &operator^= (enum_flags e) &
 172   {
 173     m_enum_value = (enum_type) (m_enum_value ^ e.m_enum_value);
 174     return *this;
 175   }
 176
 177   /* Delete rval versions.  */
 178   void operator&= (enum_flags e) && = delete;
 179   void operator|= (enum_flags e) && = delete;
 180   void operator^= (enum_flags e) && = delete;
 181
 182   /* Like raw enums, allow conversion to the underlying type.  */
 183   constexpr operator underlying_type () const
 184   {
 185     return m_enum_value;
 186   }
 187
 188   /* Get the underlying value as a raw enum.  */
 189   constexpr enum_type raw () const
 190   {
 191     return m_enum_value;
 192   }
 193
 194   /* Binary operations involving some unrelated type (which would be a
 195      bug) are implemented as non-members, and deleted.  */
 196
 197   /* Convert this object to a std::string, using MAPPING as
 198      enumerator-to-string mapping array.  This is not meant to be
 199      called directly.  Instead, enum_flags specializations should have
 200      their own to_string function wrapping this one, thus hidding the
 201      mapping array from callers.
 202
 203      Note: this is defined outside the template class so it can use
 204      the global operators for enum_type, which are only defined after
 205      the template class.  */
 206   template<size_t N>
 207   std::string to_string (const string_mapping (&mapping)[N]) const;
 208
 209 private:
 210   /* Stored as enum_type because GDB knows to print the bit flags
 211      neatly if the enum values look like bit flags.  */
 212   enum_type m_enum_value;
 213 };
 214
 215 template <typename E>
 216 using is_enum_flags_enum_type_t
 217   = decltype (is_enum_flags_enum_type (std::declval<E *> ()));
 218
 219 /* Global operator overloads.  */
 220
 221 /* Generate binary operators.  */
 222
 223 #define ENUM_FLAGS_GEN_BINOP(OPERATOR_OP, OP)                           \
 224                                                                         \
 225   /* Raw enum on both LHS/RHS.  Returns raw enum type.  */              \
 226   template <typename enum_type,                                         \
 227             typename = is_enum_flags_enum_type_t<enum_type>>            \
 228   constexpr enum_type                                                   \
 229   OPERATOR_OP (enum_type e1, enum_type e2)                              \
 230   {                                                                     \
 231     using underlying = typename enum_flags<enum_type>::underlying_type; \
 232     return (enum_type) (underlying (e1) OP underlying (e2));            \
 233   }                                                                     \
 234                                                                         \
 235   /* enum_flags on the LHS.  */                                         \
 236   template <typename enum_type,                                         \
 237             typename = is_enum_flags_enum_type_t<enum_type>>            \
 238   constexpr enum_flags<enum_type>                                       \
 239   OPERATOR_OP (enum_flags<enum_type> e1, enum_type e2)                  \
 240   { return e1.raw () OP e2; }                                           \
 241                                                                         \
 242   /* enum_flags on the RHS.  */                                         \
 243   template <typename enum_type,                                         \
 244             typename = is_enum_flags_enum_type_t<enum_type>>            \
 245   constexpr enum_flags<enum_type>                                       \
 246   OPERATOR_OP (enum_type e1, enum_flags<enum_type> e2)                  \
 247   { return e1 OP e2.raw (); }                                           \
 248                                                                         \
 249   /* enum_flags on both LHS/RHS.  */                                    \
 250   template <typename enum_type,                                         \
 251             typename = is_enum_flags_enum_type_t<enum_type>>            \
 252   constexpr enum_flags<enum_type>                                       \
 253   OPERATOR_OP (enum_flags<enum_type> e1, enum_flags<enum_type> e2)      \
 254   { return e1.raw () OP e2.raw (); }                                    \
 255                                                                         \
 256   /* Delete cases involving unrelated types.  */                        \
 257                                                                         \
 258   template <typename enum_type, typename unrelated_type,                \
 259             typename = is_enum_flags_enum_type_t<enum_type>>            \
 260   constexpr enum_flags<enum_type>                                       \
 261   OPERATOR_OP (enum_type e1, unrelated_type e2) = delete;               \
 262                                                                         \
 263   template <typename enum_type, typename unrelated_type,                \
 264             typename = is_enum_flags_enum_type_t<enum_type>>            \
 265   constexpr enum_flags<enum_type>                                       \
 266   OPERATOR_OP (unrelated_type e1, enum_type e2) = delete;               \
 267                                                                         \
 268   template <typename enum_type, typename unrelated_type,                \
 269             typename = is_enum_flags_enum_type_t<enum_type>>            \
 270   constexpr enum_flags<enum_type>                                       \
 271   OPERATOR_OP (enum_flags<enum_type> e1, unrelated_type e2) = delete;   \
 272                                                                         \
 273   template <typename enum_type, typename unrelated_type,                \
 274             typename = is_enum_flags_enum_type_t<enum_type>>            \
 275   constexpr enum_flags<enum_type>                                       \
 276   OPERATOR_OP (unrelated_type e1, enum_flags<enum_type> e2) = delete;
 277
 278 /* Generate non-member compound assignment operators.  Only the raw
 279    enum versions are defined here.  The enum_flags versions are
 280    defined as member functions, simply because it's less code that
 281    way.
 282
 283    Note we delete operators that would allow e.g.,
 284
 285      "enum_type | 1" or "enum_type1 | enum_type2"
 286
 287    because that would allow a mistake like :
 288      enum flags1 { F1_FLAGS1 = 1 };
 289      enum flags2 { F2_FLAGS2 = 2 };
 290      enum flags1 val;
 291      switch (val) {
 292        case F1_FLAGS1 | F2_FLAGS2:
 293      ...
 294
 295    If you really need to 'or' enumerators of different flag types,
 296    cast to integer first.
 297 */
 298 #define ENUM_FLAGS_GEN_COMPOUND_ASSIGN(OPERATOR_OP, OP)                 \
 299   /* lval reference version.  */                                        \
 300   template <typename enum_type,                                         \
 301             typename = is_enum_flags_enum_type_t<enum_type>>            \
 302   constexpr enum_type &                                                 \
 303   OPERATOR_OP (enum_type &e1, enum_type e2)                             \
 304   { return e1 = e1 OP e2; }                                             \
 305                                                                         \
 306   /* rval reference version.  */                                        \
 307   template <typename enum_type,                                         \
 308             typename = is_enum_flags_enum_type_t<enum_type>>            \
 309   void                                                                  \
 310   OPERATOR_OP (enum_type &&e1, enum_type e2) = delete;                  \
 311                                                                         \
 312   /* Delete compound assignment from unrelated types.  */               \
 313                                                                         \
 314   template <typename enum_type, typename other_enum_type,               \
 315             typename = is_enum_flags_enum_type_t<enum_type>>            \
 316   constexpr enum_type &                                                 \
 317   OPERATOR_OP (enum_type &e1, other_enum_type e2) = delete;             \
 318                                                                         \
 319   template <typename enum_type, typename other_enum_type,               \
 320             typename = is_enum_flags_enum_type_t<enum_type>>            \
 321   void                                                                  \
 322   OPERATOR_OP (enum_type &&e1, other_enum_type e2) = delete;
 323
 324 ENUM_FLAGS_GEN_BINOP (operator|, |)
 325 ENUM_FLAGS_GEN_BINOP (operator&, &)
 326 ENUM_FLAGS_GEN_BINOP (operator^, ^)
 327
 328 ENUM_FLAGS_GEN_COMPOUND_ASSIGN (operator|=, |)
 329 ENUM_FLAGS_GEN_COMPOUND_ASSIGN (operator&=, &)
 330 ENUM_FLAGS_GEN_COMPOUND_ASSIGN (operator^=, ^)
 331
 332 /* Allow comparison with enum_flags, raw enum, and integers, only.
 333    The latter case allows "== 0".  As side effect, it allows comparing
 334    with integer variables too, but that's not a common mistake to
 335    make.  It's important to disable comparison with unrelated types to
 336    prevent accidentally comparing with unrelated enum values, which
 337    are convertible to integer, and thus coupled with enum_flags
 338    convertion to underlying type too, would trigger the built-in 'bool
 339    operator==(unsigned, int)' operator.  */
 340
 341 #define ENUM_FLAGS_GEN_COMP(OPERATOR_OP, OP)                            \
 342                                                                         \
 343   /* enum_flags OP enum_flags */                                        \
 344                                                                         \
 345   template <typename enum_type>                                         \
 346   constexpr bool                                                        \
 347   OPERATOR_OP (enum_flags<enum_type> lhs, enum_flags<enum_type> rhs)    \
 348   { return lhs.raw () OP rhs.raw (); }                                  \
 349                                                                         \
 350   /* enum_flags OP other */                                             \
 351                                                                         \
 352   template <typename enum_type>                                         \
 353   constexpr bool                                                        \
 354   OPERATOR_OP (enum_flags<enum_type> lhs, enum_type rhs)                \
 355   { return lhs.raw () OP rhs; }                                         \
 356                                                                         \
 357   template <typename enum_type>                                         \
 358   constexpr bool                                                        \
 359   OPERATOR_OP (enum_flags<enum_type> lhs, int rhs)                      \
 360   { return lhs.raw () OP rhs; }                                         \
 361                                                                         \
 362   template <typename enum_type, typename U>                             \
 363   constexpr bool                                                        \
 364   OPERATOR_OP (enum_flags<enum_type> lhs, U rhs) = delete;              \
 365                                                                         \
 366   /* other OP enum_flags */                                             \
 367                                                                         \
 368   template <typename enum_type>                                         \
 369   constexpr bool                                                        \
 370   OPERATOR_OP (enum_type lhs, enum_flags<enum_type> rhs)                \
 371   { return lhs OP rhs.raw (); }                                         \
 372                                                                         \
 373   template <typename enum_type>                                         \
 374   constexpr bool                                                        \
 375   OPERATOR_OP (int lhs, enum_flags<enum_type> rhs)                      \
 376   { return lhs OP rhs.raw (); }                                         \
 377                                                                         \
 378   template <typename enum_type, typename U>                             \
 379   constexpr bool                                                        \
 380   OPERATOR_OP (U lhs, enum_flags<enum_type> rhs) = delete;
 381
 382 ENUM_FLAGS_GEN_COMP (operator==, ==)
 383 ENUM_FLAGS_GEN_COMP (operator!=, !=)
 384
 385 /* Unary operators for the raw flags enum.  */
 386
 387 /* We require underlying type to be unsigned when using operator~ --
 388    if it were not unsigned, undefined behavior could result.  However,
 389    asserting this in the class itself would require too many
 390    unnecessary changes to usages of otherwise OK enum types.  */
 391 template <typename enum_type,
 392           typename = is_enum_flags_enum_type_t<enum_type>,
 393           typename
 394             = gdb::Requires<enum_flags_detail::EnumIsUnsigned<enum_type>>>
 395 constexpr enum_type
 396 operator~ (enum_type e)
 397 {
 398   using underlying = typename enum_flags<enum_type>::underlying_type;
 399   return (enum_type) ~underlying (e);
 400 }
 401
 402 template <typename enum_type,
 403           typename = is_enum_flags_enum_type_t<enum_type>,
 404           typename = gdb::Requires<enum_flags_detail::EnumIsSigned<enum_type>>>
 405 constexpr void operator~ (enum_type e) = delete;
 406
 407 template <typename enum_type,
 408           typename = is_enum_flags_enum_type_t<enum_type>,
 409           typename
 410             = gdb::Requires<enum_flags_detail::EnumIsUnsigned<enum_type>>>
 411 constexpr enum_flags<enum_type>
 412 operator~ (enum_flags<enum_type> e)
 413 {
 414   using underlying = typename enum_flags<enum_type>::underlying_type;
 415   return (enum_type) ~underlying (e);
 416 }
 417
 418 template <typename enum_type,
 419           typename = is_enum_flags_enum_type_t<enum_type>,
 420           typename = gdb::Requires<enum_flags_detail::EnumIsSigned<enum_type>>>
 421 constexpr void operator~ (enum_flags<enum_type> e) = delete;
 422
 423 /* Delete operator<< and operator>>.  */
 424
 425 template <typename enum_type, typename any_type,
 426           typename = is_enum_flags_enum_type_t<enum_type>>
 427 void operator<< (const enum_type &, const any_type &) = delete;
 428
 429 template <typename enum_type, typename any_type,
 430           typename = is_enum_flags_enum_type_t<enum_type>>
 431 void operator<< (const enum_flags<enum_type> &, const any_type &) = delete;
 432
 433 template <typename enum_type, typename any_type,
 434           typename = is_enum_flags_enum_type_t<enum_type>>
 435 void operator>> (const enum_type &, const any_type &) = delete;
 436
 437 template <typename enum_type, typename any_type,
 438           typename = is_enum_flags_enum_type_t<enum_type>>
 439 void operator>> (const enum_flags<enum_type> &, const any_type &) = delete;
 440
 441 template<typename E>
 442 template<size_t N>
 443 std::string
 444 enum_flags<E>::to_string (const string_mapping (&mapping)[N]) const
 445 {
 446   enum_type flags = raw ();
 447   std::string res = hex_string (flags);
 448   res += " [";
 449
 450   bool need_space = false;
 451   for (const auto &entry : mapping)
 452     {
 453       if ((flags & entry.flag) != 0)
 454         {
 455           /* Work with an unsigned version of the underlying type,
 456              because if enum_type's underlying type is signed, op~
 457              won't be defined for it, and, bitwise operations on
 458              signed types are implementation defined.  */
 459           using uns = typename std::make_unsigned<underlying_type>::type;
 460           flags &= (enum_type) ~(uns) entry.flag;
 461
 462           if (need_space)
 463             res += " ";
 464           res += entry.str;
 465
 466           need_space = true;
 467         }
 468     }
 469
 470   /* If there were flags not included in the mapping, print them as
 471      a hex number.  */
 472   if (flags != 0)
 473     {
 474       if (need_space)
 475         res += " ";
 476       res += hex_string (flags);
 477     }
 478
 479   res += "]";
 480
 481   return res;
 482 }
 483
 484 #else /* __cplusplus */
 485
 486 /* In C, the flags type is just a typedef for the enum type.  */
 487
 488 #define DEF_ENUM_FLAGS_TYPE(enum_type, flags_type) \
 489   typedef enum_type flags_type
 490
 491 #endif /* __cplusplus */
 492
 493 #endif /* COMMON_ENUM_FLAGS_H */