mfbt/DefineEnum.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 /* Poor man's reflection for enumerations. */
   8
   9 #ifndef mozilla_DefineEnum_h
  10 #define mozilla_DefineEnum_h
  11
  12 #include <stddef.h>  // for size_t
  13
  14 #include "mozilla/MacroArgs.h"     // for MOZ_ARG_COUNT
  15 #include "mozilla/MacroForEach.h"  // for MOZ_FOR_EACH
  16
  17 /**
  18  * MOZ_UNWRAP_ARGS is a helper macro that unwraps a list of comma-separated
  19  * items enclosed in parentheses, to yield just the items.
  20  *
  21  * Usage: |MOZ_UNWRAP_ARGS foo| (note the absence of parentheses in the
  22  * invocation), where |foo| is a parenthesis-enclosed list.
  23  * For exampe if |foo| is |(3, 4, 5)|, then the expansion is just |3, 4, 5|.
  24  */
  25 #define MOZ_UNWRAP_ARGS(...) __VA_ARGS__
  26
  27 /**
  28  * MOZ_DEFINE_ENUM(aEnumName, aEnumerators) is a macro that allows
  29  * simultaneously defining an enumeration named |aEnumName|, and a constant
  30  * that stores the number of enumerators it has.
  31  *
  32  * The motivation is to allow the enumeration to evolve over time without
  33  * either having to manually keep such a constant up to date, or having to
  34  * add a special "sentinel" enumerator for this purpose. (While adding a
  35  * "sentinel" enumerator is trivial, it causes headaches with "switch"
  36  * statements. We often try to write "switch" statements whose cases exhaust
  37  * the enumerators and don't have a "default" case, so that if a new
  38  * enumerator is added and we forget to handle it in the "switch", the
  39  * compiler points it out. But this means we need to explicitly handle the
  40  * sentinel in every "switch".)
  41  *
  42  * |aEnumerators| is expected to be a comma-separated list of enumerators,
  43  * enclosed in parentheses. The enumerators may NOT have associated
  44  * initializers (an attempt to have one will result in a compiler error).
  45  * This ensures that the enumerator values are in the range [0, N), where N
  46  * is the number of enumerators.
  47  *
  48  * The list of enumerators cannot contain a trailing comma. This is a
  49  * limitation of MOZ_FOR_EACH, which we use in the implementation; if
  50  * MOZ_FOR_EACH supported trailing commas, we could too.
  51  *
  52  * The generated constant has the name "k" + |aEnumName| + "Count", and type
  53  * "size_t". The enumeration and the constant are both defined in the scope
  54  * in which the macro is invoked.
  55  *
  56  * For convenience, a constant of the enumeration type named
  57  * "kHighest" + |aEnumName| is also defined, whose value is the highest
  58  * valid enumerator, assuming the enumerators have contiguous values starting
  59  * from 0.
  60  *
  61  * Invocation of the macro may be followed by a semicolon, if one prefers a
  62  * more declaration-like syntax.
  63  *
  64  * Example invocation:
  65  *   MOZ_DEFINE_ENUM(MyEnum, (Foo, Bar, Baz));
  66  *
  67  * This expands to:
  68  *   enum MyEnum { Foo, Bar, Baz };
  69  *   constexpr size_t kMyEnumCount = 3;
  70  *   constexpr MyEnum kHighestMyEnum = MyEnum(kMyEnumCount - 1);
  71  *   // some static_asserts to ensure the values are in the range [0, 3)
  72  *
  73  * The macro also has several variants:
  74  *
  75  *    - A |_CLASS| variant, which generates an |enum class| instead of
  76  *      a plain enum.
  77  *
  78  *    - A |_WITH_BASE| variant which generates an enum with a specified
  79  *      underlying ("base") type, which is provided as an additional
  80  *      argument in second position.
  81  *
  82  *    - An |_AT_CLASS_SCOPE| variant, designed for enumerations defined
  83  *      at class scope. For these, the generated constants are static,
  84  *      and have names prefixed with "s" instead of "k" as per
  85  *      naming convention.
  86  *
  87  *  (and combinations of these).
  88  */
  89
  90 /*
  91  * A helper macro for asserting that an enumerator does not have an initializer.
  92  *
  93  * The static_assert and the comparison are just scaffolding; the important
  94  * part is forming the expression |aEnumName::aEnumeratorDecl|.
  95  *
  96  * If |aEnumeratorDecl| is just the enumerator name without an identifier,
  97  * this expression compiles fine. However, if |aEnumeratorDecl| includes an
  98  * initializer, as in |eEnumerator = initializer|, then this will fail to
  99  * compile in expression context, since |eEnumerator| is not an lvalue.
 100  *
 101  * (The static_assert itself should always pass in the absence of the above
 102  * error, since turning on a bit can only increase an integer value. It just
 103  * provides a place to put the expression we want to form.)
 104  */
 105
 106 #define MOZ_ASSERT_ENUMERATOR_HAS_NO_INITIALIZER(aEnumName, aEnumeratorDecl) \
 107   static_assert(                                                             \
 108       int(aEnumName::aEnumeratorDecl) <=                                     \
 109           (int(aEnumName::aEnumeratorDecl) | 1),                             \
 110       "MOZ_DEFINE_ENUM does not allow enumerators to have initializers");
 111
 112 #define MOZ_DEFINE_ENUM_IMPL(aEnumName, aClassSpec, aBaseSpec, aEnumerators) \
 113   enum aClassSpec aEnumName aBaseSpec{MOZ_UNWRAP_ARGS aEnumerators};         \
 114   constexpr size_t k##aEnumName##Count = MOZ_ARG_COUNT aEnumerators;         \
 115   constexpr aEnumName kHighest##aEnumName =                                  \
 116       aEnumName(k##aEnumName##Count - 1);                                    \
 117   MOZ_FOR_EACH(MOZ_ASSERT_ENUMERATOR_HAS_NO_INITIALIZER, (aEnumName, ),      \
 118                aEnumerators)
 119
 120 #define MOZ_DEFINE_ENUM(aEnumName, aEnumerators) \
 121   MOZ_DEFINE_ENUM_IMPL(aEnumName, , , aEnumerators)
 122
 123 #define MOZ_DEFINE_ENUM_WITH_BASE(aEnumName, aBaseName, aEnumerators) \
 124   MOZ_DEFINE_ENUM_IMPL(aEnumName, , : aBaseName, aEnumerators)
 125
 126 #define MOZ_DEFINE_ENUM_CLASS(aEnumName, aEnumerators) \
 127   MOZ_DEFINE_ENUM_IMPL(aEnumName, class, , aEnumerators)
 128
 129 #define MOZ_DEFINE_ENUM_CLASS_WITH_BASE(aEnumName, aBaseName, aEnumerators) \
 130   MOZ_DEFINE_ENUM_IMPL(aEnumName, class, : aBaseName, aEnumerators)
 131
 132 #define MOZ_DEFINE_ENUM_AT_CLASS_SCOPE_IMPL(aEnumName, aClassSpec, aBaseSpec, \
 133                                             aEnumerators)                     \
 134   enum aClassSpec aEnumName aBaseSpec{MOZ_UNWRAP_ARGS aEnumerators};          \
 135   constexpr static size_t s##aEnumName##Count = MOZ_ARG_COUNT aEnumerators;   \
 136   constexpr static aEnumName sHighest##aEnumName =                            \
 137       aEnumName(s##aEnumName##Count - 1);                                     \
 138   MOZ_FOR_EACH(MOZ_ASSERT_ENUMERATOR_HAS_NO_INITIALIZER, (aEnumName, ),       \
 139                aEnumerators)
 140
 141 #define MOZ_DEFINE_ENUM_AT_CLASS_SCOPE(aEnumName, aEnumerators) \
 142   MOZ_DEFINE_ENUM_AT_CLASS_SCOPE_IMPL(aEnumName, , , aEnumerators)
 143
 144 #define MOZ_DEFINE_ENUM_WITH_BASE_AT_CLASS_SCOPE(aEnumName, aBaseName, \
 145                                                  aEnumerators)         \
 146   MOZ_DEFINE_ENUM_AT_CLASS_SCOPE_IMPL(aEnumName, , : aBaseName, aEnumerators)
 147
 148 #define MOZ_DEFINE_ENUM_CLASS_AT_CLASS_SCOPE(aEnumName, aEnumerators) \
 149   MOZ_DEFINE_ENUM_AT_CLASS_SCOPE_IMPL(aEnumName, class, , aEnumerators)
 150
 151 #define MOZ_DEFINE_ENUM_CLASS_WITH_BASE_AT_CLASS_SCOPE(aEnumName, aBaseName, \
 152                                                        aEnumerators)         \
 153   MOZ_DEFINE_ENUM_AT_CLASS_SCOPE_IMPL(aEnumName, class,                      \
 154                                       : aBaseName, aEnumerators)
 155
 156 #endif  // mozilla_DefineEnum_h