2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2019,2020, 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.
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.
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.
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.
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.
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.
36 * \brief Defines helper types for class enumerations.
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
45 * NOTE This functionality only works for enumerations of monotonically
46 * increasing values, starting with the value zero.
50 * enum class Foo : int
58 * for (Foo c : EnumerationWrapper<Foo>{})
60 * // 'c' is a constant from Foo
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
68 * for (Foo c : keysOf(fooStrings))
70 * print(fooStrings[c]);
73 * ArrayRef<const std::string> namesRef(fooStrings);
75 * \author Mark Abraham <mark.j.abraham@gmail.com>
77 * \ingroup module_utility
79 #ifndef GMX_UTILITY_ENUMHELPERS_H
80 #define GMX_UTILITY_ENUMHELPERS_H
85 #include <type_traits>
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>
93 #include "gromacs/utility/gmxassert.h"
99 * \brief Allows iterating sequential enumerators.
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.
106 * NOTE This functionality only works for enumerations of monotonically
107 * increasing values, starting with the value zero.
109 * See file documentation for usage example.
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.
115 template<typename EnumType, EnumType Last = EnumType::Count, unsigned int Step = 1>
116 class EnumerationIterator final :
117 public boost::stl_interfaces::iterator_interface<EnumerationIterator<EnumType, Last, Step>, std::random_access_iterator_tag, EnumType>
120 //! Convenience alias
121 using IntegerType = std::underlying_type_t<EnumType>;
123 constexpr EnumerationIterator() noexcept : m_current{ 0 } // Assumes 0 is the first constant
126 //! Conversion constructor
127 explicit constexpr EnumerationIterator(const EnumType index) noexcept :
128 m_current(static_cast<IntegerType>(index))
131 //! Addition-assignment operator
132 constexpr EnumerationIterator& operator+=(std::ptrdiff_t i) noexcept
134 m_current += Step * i;
137 //! Dereference operator
138 constexpr EnumType operator*() const noexcept
140 GMX_ASSERT(m_current < static_cast<IntegerType>(Last), "dereferencing out of range");
141 return static_cast<EnumType>(m_current);
143 //! Difference operator
144 constexpr std::ptrdiff_t operator-(const EnumerationIterator other) const noexcept
146 return (m_current - other.m_current) / Step;
150 IntegerType m_current;
154 * \brief Allows constructing iterators for looping over sequential enumerators.
156 * These are particularly useful for range-based for statements.
158 * You can also provide an increment step > 1 if each constant is
159 * spaced by a larger value. Terminating constant is assumed to be a
160 * 'Count' member, which is never iterated. A different name for the
161 * terminating constant can also be specified on declaration.
163 * See file documentation for usage example.
165 * \tparam EnumType The enum (class) type.
166 * \tparam Last Last constant or number thereof (assumes a default 'Count' member).
167 * \tparam Step Step increment.
169 template<typename EnumType, EnumType Last = EnumType::Count, unsigned int Step = 1>
170 class EnumerationWrapper final
173 //! Convenience alias.
174 using IteratorType = EnumerationIterator<EnumType, Last, Step>;
176 //! Functions required for range-based for statements to work.
178 IteratorType begin() const { return IteratorType{}; }
179 IteratorType end() const { return IteratorType{ Last }; }
184 * \brief Wrapper for a C-style array with size and indexing defined
185 * by an enum. Useful for declaring arrays of enum names for debug
186 * or other printing. An ArrayRef<DataType> may be constructed from
187 * an object of this type.
189 * See file documentation for usage example.
191 * \tparam EnumType The enum (class) type.
192 * \tparam DataType Type of the data stored in the array.
193 * \tparam ArraySize Size in entries of the array.
195 template<typename EnumType, // The enum (class) type.
196 typename DataType, // Type of the data stored in the array.
197 EnumType ArraySize = EnumType::Count // Size in entries of the array.
199 struct EnumerationArray final
201 //! Convenience alias
202 using EnumerationWrapperType = EnumerationWrapper<EnumType, ArraySize>;
204 /*! \brief Data for names.
206 * Data is kept public so we can use direct aggregate
207 * initialization just like in a plain C-style array. */
208 DataType m_elements[std::size_t(ArraySize)];
210 //! Returns an object that provides iterators over the keys.
211 static constexpr EnumerationWrapperType keys() { return EnumerationWrapperType{}; }
212 //! Returns the size of the enumeration.
213 static constexpr std::size_t size() { return std::size_t(ArraySize); }
216 //! Array access with asserts:
217 DataType& operator[](const std::size_t index)
219 GMX_ASSERT(index < size(), "index out of range");
220 return m_elements[index];
222 const DataType& operator[](const std::size_t index) const
224 GMX_ASSERT(index < size(), "index out of range");
225 return m_elements[index];
228 DataType& operator[](const EnumType index)
230 GMX_ASSERT(std::size_t(index) < size(), "index out of range");
231 return m_elements[std::size_t(index)];
233 const DataType& operator[](const EnumType index) const
235 GMX_ASSERT(std::size_t(index) < size(), "index out of range");
236 return m_elements[std::size_t(index)];
241 //! Range iterators (unchecked)
242 using iterator = DataType*;
243 using const_iterator = const DataType*;
244 using reverse_iterator = std::reverse_iterator<iterator>;
245 using const_reverse_iterator = std::reverse_iterator<const_iterator>;
249 //! Getters for forward iterators for ranges
250 iterator begin() { return &m_elements[0]; }
251 iterator end() { return &m_elements[size()]; }
252 const_iterator begin() const { return &m_elements[0]; }
253 const_iterator end() const { return &m_elements[size()]; }
257 //! Getters for reverse iterators for ranges
258 reverse_iterator rbegin() { return reverse_iterator{ end() }; }
259 reverse_iterator rend() { return reverse_iterator{ begin() }; }
260 const_reverse_iterator rbegin() const { return const_reverse_iterator{ end() }; }
261 const_reverse_iterator rend() const { return const_reverse_iterator{ begin() }; }
265 //! Pointers (unchecked)
266 using pointer = DataType*;
267 using const_pointer = const DataType*;
270 //! Returns a const raw pointer to the contents of the array.
271 const_pointer data() const { return &m_elements[0]; }
272 //! Returns a raw pointer to the contents of the array.
273 pointer data() { return &m_elements[0]; }
276 /*! \brief Returns an object that provides iterators over the keys
277 * associated with \c EnumerationArrayType.
279 * This helper function is useful in contexts where there is an object
280 * of an EnumerationArray, and we want to use a range-based for loop
281 * over the keys associated with it, and it would be inconvenient to
282 * use the very word EnumerationArray<...> type, nor introduce a using
283 * statement for this purpose. It is legal in C++ to call a static
284 * member function (such as keys()) via an object rather than the
285 * type, but clang-tidy warns about that. So instead we make available
286 * a free function that calls that static method. */
287 template<typename EnumerationArrayType>
288 typename EnumerationArrayType::EnumerationWrapperType keysOf(const EnumerationArrayType& /* arrayObject */)
290 return EnumerationArrayType::keys();