DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (8ba01fc4f7e0)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155
/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set ts=8 sts=2 et sw=2 tw=80: */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

/* Poor man's reflection for enumerations. */

#ifndef mozilla_DefineEnum_h
#define mozilla_DefineEnum_h

#include <stddef.h>  // for size_t

#include "mozilla/MacroArgs.h"     // for MOZ_ARG_COUNT
#include "mozilla/MacroForEach.h"  // for MOZ_FOR_EACH

/**
 * MOZ_UNWRAP_ARGS is a helper macro that unwraps a list of comma-separated
 * items enclosed in parentheses, to yield just the items.
 *
 * Usage: |MOZ_UNWRAP_ARGS foo| (note the absence of parentheses in the
 * invocation), where |foo| is a parenthesis-enclosed list.
 * For exampe if |foo| is |(3, 4, 5)|, then the expansion is just |3, 4, 5|.
 */
#define MOZ_UNWRAP_ARGS(...) __VA_ARGS__

/**
 * MOZ_DEFINE_ENUM(aEnumName, aEnumerators) is a macro that allows
 * simultaneously defining an enumeration named |aEnumName|, and a constant
 * that stores the number of enumerators it has.
 *
 * The motivation is to allow the enumeration to evolve over time without
 * either having to manually keep such a constant up to date, or having to
 * add a special "sentinel" enumerator for this purpose. (While adding a
 * "sentinel" enumerator is trivial, it causes headaches with "switch"
 * statements. We often try to write "switch" statements whose cases exhaust
 * the enumerators and don't have a "default" case, so that if a new
 * enumerator is added and we forget to handle it in the "switch", the
 * compiler points it out. But this means we need to explicitly handle the
 * sentinel in every "switch".)
 *
 * |aEnumerators| is expected to be a comma-separated list of enumerators,
 * enclosed in parentheses. The enumerators may NOT have associated
 * initializers (an attempt to have one will result in a compiler error).
 * This ensures that the enumerator values are in the range [0, N), where N
 * is the number of enumerators.
 *
 * The list of enumerators cannot contain a trailing comma. This is a
 * limitation of MOZ_FOR_EACH, which we use in the implementation; if
 * MOZ_FOR_EACH supported trailing commas, we could too.
 *
 * The generated constant has the name "k" + |aEnumName| + "Count", and type
 * "size_t". The enumeration and the constant are both defined in the scope
 * in which the macro is invoked.
 *
 * For convenience, a constant of the enumeration type named
 * "kHighest" + |aEnumName| is also defined, whose value is the highest
 * valid enumerator, assuming the enumerators have contiguous values starting
 * from 0.
 *
 * Invocation of the macro may be followed by a semicolon, if one prefers a
 * more declaration-like syntax.
 *
 * Example invocation:
 *   MOZ_DEFINE_ENUM(MyEnum, (Foo, Bar, Baz));
 *
 * This expands to:
 *   enum MyEnum { Foo, Bar, Baz };
 *   constexpr size_t kMyEnumCount = 3;
 *   constexpr MyEnum kHighestMyEnum = MyEnum(kMyEnumCount - 1);
 *   // some static_asserts to ensure the values are in the range [0, 3)
 *
 * The macro also has several variants:
 *
 *    - A |_CLASS| variant, which generates an |enum class| instead of
 *      a plain enum.
 *
 *    - A |_WITH_BASE| variant which generates an enum with a specified
 *      underlying ("base") type, which is provided as an additional
 *      argument in second position.
 *
 *    - An |_AT_CLASS_SCOPE| variant, designed for enumerations defined
 *      at class scope. For these, the generated constants are static,
 *      and have names prefixed with "s" instead of "k" as per
 *      naming convention.
 *
 *  (and combinations of these).
 */

/*
 * A helper macro for asserting that an enumerator does not have an initializer.
 *
 * The static_assert and the comparison to 0 are just scaffolding; the
 * important part is forming the expression |aEnumName::aEnumeratorDecl|.
 *
 * If |aEnumeratorDecl| is just the enumerator name without an identifier,
 * this expression compiles fine. However, if |aEnumeratorDecl| includes an
 * initializer, as in |eEnumerator = initializer|, then this will fail to
 * compile in expression context, since |eEnumerator| is not an lvalue.
 *
 * (The static_assert itself should always pass in the absence of the above
 * error, since you can't get a negative enumerator value without having
 * an initializer somewhere. It just provides a place to put the expression
 * we want to form.)
 */
#define MOZ_ASSERT_ENUMERATOR_HAS_NO_INITIALIZER(aEnumName, aEnumeratorDecl) \
  static_assert(                                                             \
      (aEnumName::aEnumeratorDecl) >= aEnumName(0),                          \
      "MOZ_DEFINE_ENUM does not allow enumerators to have initializers");

#define MOZ_DEFINE_ENUM_IMPL(aEnumName, aClassSpec, aBaseSpec, aEnumerators) \
  enum aClassSpec aEnumName aBaseSpec{MOZ_UNWRAP_ARGS aEnumerators};         \
  constexpr size_t k##aEnumName##Count = MOZ_ARG_COUNT aEnumerators;         \
  constexpr aEnumName k##Highest##aEnumName =                                \
      aEnumName(k##aEnumName##Count - 1);                                    \
  MOZ_FOR_EACH(MOZ_ASSERT_ENUMERATOR_HAS_NO_INITIALIZER, (aEnumName, ),      \
               aEnumerators)

#define MOZ_DEFINE_ENUM(aEnumName, aEnumerators) \
  MOZ_DEFINE_ENUM_IMPL(aEnumName, , , aEnumerators)

#define MOZ_DEFINE_ENUM_WITH_BASE(aEnumName, aBaseName, aEnumerators) \
  MOZ_DEFINE_ENUM_IMPL(aEnumName, , : aBaseName, aEnumerators)

#define MOZ_DEFINE_ENUM_CLASS(aEnumName, aEnumerators) \
  MOZ_DEFINE_ENUM_IMPL(aEnumName, class, , aEnumerators)

#define MOZ_DEFINE_ENUM_CLASS_WITH_BASE(aEnumName, aBaseName, aEnumerators) \
  MOZ_DEFINE_ENUM_IMPL(aEnumName, class, : aBaseName, aEnumerators)

#define MOZ_DEFINE_ENUM_AT_CLASS_SCOPE_IMPL(aEnumName, aClassSpec, aBaseSpec, \
                                            aEnumerators)                     \
  enum aClassSpec aEnumName aBaseSpec{MOZ_UNWRAP_ARGS aEnumerators};          \
  constexpr static size_t s##aEnumName##Count = MOZ_ARG_COUNT aEnumerators;   \
  constexpr static aEnumName s##Highest##aEnumName =                          \
      aEnumName(s##aEnumName##Count - 1);                                     \
  MOZ_FOR_EACH(MOZ_ASSERT_ENUMERATOR_HAS_NO_INITIALIZER, (aEnumName, ),       \
               aEnumerators)

#define MOZ_DEFINE_ENUM_AT_CLASS_SCOPE(aEnumName, aEnumerators) \
  MOZ_DEFINE_ENUM_AT_CLASS_SCOPE_IMPL(aEnumName, , , aEnumerators)

#define MOZ_DEFINE_ENUM_WITH_BASE_AT_CLASS_SCOPE(aEnumName, aBaseName, \
                                                 aEnumerators)         \
  MOZ_DEFINE_ENUM_AT_CLASS_SCOPE_IMPL(aEnumName, , : aBaseName, aEnumerators)

#define MOZ_DEFINE_ENUM_CLASS_AT_CLASS_SCOPE(aEnumName, aEnumerators) \
  MOZ_DEFINE_ENUM_AT_CLASS_SCOPE_IMPL(aEnumName, class, , aEnumerators)

#define MOZ_DEFINE_ENUM_CLASS_WITH_BASE_AT_CLASS_SCOPE(aEnumName, aBaseName, \
                                                       aEnumerators)         \
  MOZ_DEFINE_ENUM_AT_CLASS_SCOPE_IMPL(aEnumName, class,                      \
                                      : aBaseName, aEnumerators)

#endif  // mozilla_DefineEnum_h