src/gromacs/utility/enumerationhelpers.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2019,2020,2021, by the GROMACS development team, led by
   5  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   6  * and including many others, as listed in the AUTHORS file in the
   7  * top-level source directory and at http://www.gromacs.org.
   8  *
   9  * GROMACS is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public License
  11  * as published by the Free Software Foundation; either version 2.1
  12  * of the License, or (at your option) any later version.
  13  *
  14  * GROMACS is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with GROMACS; if not, see
  21  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  22  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  23  *
  24  * If you want to redistribute modifications to GROMACS, please
  25  * consider that scientific software is very special. Version
  26  * control is crucial - bugs must be traceable. We will be happy to
  27  * consider code for inclusion in the official distribution, but
  28  * derived work must not be called official GROMACS. Details are found
  29  * in the README & COPYING files - if they are missing, get the
  30  * official version at http://www.gromacs.org.
  31  *
  32  * To help us fund GROMACS development, we humbly ask that you cite
  33  * the research papers on the package. Check out http://www.gromacs.org.
  34  */
  35 /*! \file
  36  * \brief Defines helper types for class enumerations.
  37  *
  38  * These helper types facilitate iterating over class enums, and
  39  * maintaining a type-safe and value-safe matching list of names. The
  40  * code is closely based on the public-domain code by Guilherme
  41  * R. Lampert, found in commit c94c18a of
  42  * https://github.com/glampert/enum_helpers/blob/master/enum_helpers.hpp
  43  * Thanks Guilherme!
  44  *
  45  * NOTE This functionality only works for enumerations of monotonically
  46  * increasing values, starting with the value zero.
  47  *
  48  * Usage examples:
  49  *
  50  *  enum class Foo : int
  51  *  {
  52  *      Bar,
  53  *      Baz,
  54  *      Fooz,
  55  *      Count
  56  *  };
  57  *
  58  *  for (Foo c : EnumerationWrapper<Foo>{})
  59  *  {
  60  *      // 'c' is a constant from Foo
  61  *  }
  62  *
  63  *
  64  *  const EnumerationArray<Foo, std::string> fooStrings = { { "Bar", "Baz", "Fooz" } };
  65  *  std::cout << fooStrings[Foo::Baz];
  66  *  std::cout << fooStrings[Foo::Count]; // Triggers an assertion
  67  *
  68  *  for (Foo c : keysOf(fooStrings))
  69  *  {
  70  *      print(fooStrings[c]);
  71  *  }
  72  *
  73  *  ArrayRef<const std::string> namesRef(fooStrings);
  74  *
  75  * \author Mark Abraham <mark.j.abraham@gmail.com>
  76  * \inlibraryapi
  77  * \ingroup module_utility
  78  */
  79 #ifndef GMX_UTILITY_ENUMHELPERS_H
  80 #define GMX_UTILITY_ENUMHELPERS_H
  81
  82 #include <cstddef>
  83
  84 #include <iterator>
  85 #include <type_traits>
  86
  87 #if __has_include(<boost/stl_interfaces/iterator_interface.hpp>)
  88 #    include <boost/stl_interfaces/iterator_interface.hpp>
  89 #else // fallback for installed headers
  90 #    include <gromacs/external/boost/stl_interfaces/iterator_interface.hpp>
  91 #endif
  92
  93 #include "gromacs/utility/gmxassert.h"
  94
  95 namespace gmx
  96 {
  97
  98 /*! \libinternal
  99  * \brief Allows iterating sequential enumerators.
 100  *
 101  * You can also provide an increment step > 1 if each constant is
 102  * spaced by a larger value.  Terminating constant is assumed to be a
 103  * 'Count' member, which is never iterated. A different name for the
 104  * terminating constant can also be specified on declaration.
 105  *
 106  * NOTE This functionality only works for enumerations of monotonically
 107  * increasing values, starting with the value zero.
 108  *
 109  * See file documentation for usage example.
 110  *
 111  * \tparam  EnumType   The enum (class) type.
 112  * \tparam  Last       Last constant or number thereof (assumes a default 'Count' member).
 113  * \tparam  Step       Step increment.
 114  */
 115 template<typename EnumType, EnumType Last = EnumType::Count, std::ptrdiff_t Step = 1>
 116 class EnumerationIterator final :
 117     public boost::stl_interfaces::iterator_interface<EnumerationIterator<EnumType, Last, Step>, std::random_access_iterator_tag, EnumType>
 118 {
 119 public:
 120     // TODO: Use std::is_enum_v when CUDA 11 is a requirement.
 121     static_assert(std::is_enum<EnumType>::value, "Enumeration iterator must be over an enum type.");
 122     //! Convenience alias
 123     using IntegerType = std::underlying_type_t<EnumType>;
 124
 125     constexpr EnumerationIterator() noexcept : m_current{ 0 } // Assumes 0 is the first constant
 126     {
 127     }
 128     //! Conversion constructor
 129     explicit constexpr EnumerationIterator(const EnumType index) noexcept :
 130         m_current(static_cast<IntegerType>(index))
 131     {
 132     }
 133     //! Addition-assignment operator
 134     constexpr EnumerationIterator& operator+=(std::ptrdiff_t i) noexcept
 135     {
 136         m_current += Step * i;
 137         return *this;
 138     }
 139     //! Dereference operator
 140     constexpr EnumType operator*() const noexcept
 141     {
 142         GMX_ASSERT(m_current < static_cast<IntegerType>(Last), "dereferencing out of range");
 143         return static_cast<EnumType>(m_current);
 144     }
 145     //! Difference operator
 146     constexpr std::ptrdiff_t operator-(const EnumerationIterator other) const noexcept
 147     {
 148         return (static_cast<std::ptrdiff_t>(m_current) - static_cast<std::ptrdiff_t>(other.m_current)) / Step;
 149     }
 150
 151 private:
 152     IntegerType m_current;
 153 };
 154
 155 /*! \libinternal
 156  * \brief Allows constructing iterators for looping over sequential enumerators.
 157  *
 158  * These are particularly useful for range-based for statements.
 159  *
 160  * You can also provide an increment step > 1 if each constant is
 161  * spaced by a larger value.  Terminating constant is assumed to be a
 162  * 'Count' member, which is never iterated. A different name for the
 163  * terminating constant can also be specified on declaration.
 164  *
 165  * See file documentation for usage example.
 166  *
 167  * \tparam  EnumType   The enum (class) type.
 168  * \tparam  Last       Last constant or number thereof (assumes a default 'Count' member).
 169  * \tparam  Step       Step increment.
 170  */
 171 template<typename EnumType, EnumType Last = EnumType::Count, unsigned int Step = 1>
 172 class EnumerationWrapper final
 173 {
 174 public:
 175     //! Convenience alias.
 176     using IteratorType = EnumerationIterator<EnumType, Last, Step>;
 177
 178     //! Functions required for range-based for statements to work.
 179     /*!@{*/
 180     IteratorType begin() const { return IteratorType{}; }
 181     IteratorType end() const { return IteratorType{ Last }; }
 182     /*!@}*/
 183 };
 184
 185 /*! \libinternal
 186  * \brief Wrapper for a C-style array with size and indexing defined
 187  * by an enum. Useful for declaring arrays of enum names for debug
 188  * or other printing. An ArrayRef<DataType> may be constructed from
 189  * an object of this type.
 190  *
 191  * See file documentation for usage example.
 192  *
 193  * Note that if clang-tidy gives strange errors referring to the line
 194  * number of the struct declaration, these likely refer to the
 195  * compiler-generated constructors. Simplification of the calling code
 196  * might eliminate that call and thus the clang-tidy error.
 197  *
 198  * \tparam  EnumType   The enum (class) type.
 199  * \tparam  DataType   Type of the data stored in the array.
 200  * \tparam  ArraySize  Size in entries of the array.
 201  */
 202 template<typename EnumType, typename DataType, EnumType ArraySize = EnumType::Count>
 203 struct EnumerationArray final
 204 {
 205     //! Convenience alias
 206     using EnumerationWrapperType = EnumerationWrapper<EnumType, ArraySize>;
 207
 208     //! Convenience alias
 209     using value_type = DataType;
 210
 211     /*! \brief Data for names.
 212      *
 213      * Data is kept public so we can use direct aggregate
 214      * initialization just like in a plain C-style array. */
 215     DataType m_elements[std::size_t(ArraySize)];
 216
 217     //! Returns an object that provides iterators over the keys.
 218     static constexpr EnumerationWrapperType keys() { return EnumerationWrapperType{}; }
 219     //! Returns the size of the enumeration.
 220     constexpr std::size_t size() const { return std::size_t(ArraySize); }
 221
 222     /*!@{*/
 223     //! Array access with asserts:
 224     DataType& operator[](const std::size_t index)
 225     {
 226         GMX_ASSERT(index < size(), "index out of range");
 227         return m_elements[index];
 228     }
 229     const DataType& operator[](const std::size_t index) const
 230     {
 231         GMX_ASSERT(index < size(), "index out of range");
 232         return m_elements[index];
 233     }
 234
 235     DataType& operator[](const EnumType index)
 236     {
 237         GMX_ASSERT(std::size_t(index) < size(), "index out of range");
 238         return m_elements[std::size_t(index)];
 239     }
 240     const DataType& operator[](const EnumType index) const
 241     {
 242         GMX_ASSERT(std::size_t(index) < size(), "index out of range");
 243         return m_elements[std::size_t(index)];
 244     }
 245     /*!@}*/
 246
 247     /*!@{*/
 248     //! Range iterators (unchecked)
 249     using iterator               = DataType*;
 250     using const_iterator         = const DataType*;
 251     using reverse_iterator       = std::reverse_iterator<iterator>;
 252     using const_reverse_iterator = std::reverse_iterator<const_iterator>;
 253     /*!@}*/
 254
 255     /*!@{*/
 256     //! Getters for forward iterators for ranges
 257     iterator       begin() { return &m_elements[0]; }
 258     iterator       end() { return &m_elements[size()]; }
 259     const_iterator begin() const { return &m_elements[0]; }
 260     const_iterator end() const { return &m_elements[size()]; }
 261     /*!@}*/
 262
 263     /*!@{*/
 264     //! Getters for reverse iterators for ranges
 265     reverse_iterator       rbegin() { return reverse_iterator{ end() }; }
 266     reverse_iterator       rend() { return reverse_iterator{ begin() }; }
 267     const_reverse_iterator rbegin() const { return const_reverse_iterator{ end() }; }
 268     const_reverse_iterator rend() const { return const_reverse_iterator{ begin() }; }
 269     /*!@}*/
 270
 271     /*!@{*/
 272     //! Pointers (unchecked)
 273     using pointer       = DataType*;
 274     using const_pointer = const DataType*;
 275     /*!@}*/
 276
 277     //! Returns a const raw pointer to the contents of the array.
 278     const_pointer data() const { return &m_elements[0]; }
 279     //! Returns a raw pointer to the contents of the array.
 280     pointer data() { return &m_elements[0]; }
 281 };
 282
 283 /*! \brief Returns an object that provides iterators over the keys
 284  * associated with \c EnumerationArrayType.
 285  *
 286  * This helper function is useful in contexts where there is an object
 287  * of an EnumerationArray, and we want to use a range-based for loop
 288  * over the keys associated with it, and it would be inconvenient to
 289  * use the very word EnumerationArray<...> type, nor introduce a using
 290  * statement for this purpose. It is legal in C++ to call a static
 291  * member function (such as keys()) via an object rather than the
 292  * type, but clang-tidy warns about that. So instead we make available
 293  * a free function that calls that static method. */
 294 template<typename EnumerationArrayType>
 295 typename EnumerationArrayType::EnumerationWrapperType keysOf(const EnumerationArrayType& /* arrayObject */)
 296 {
 297     return EnumerationArrayType::keys();
 298 }
 299
 300 } // namespace gmx
 301
 302 #endif