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
, 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
>
120 static_assert(std::is_enum_v
<EnumType
>, "Enumeration iterator must be over an enum type.");
121 //! Convenience alias
122 using IntegerType
= std::underlying_type_t
<EnumType
>;
124 constexpr EnumerationIterator() noexcept
: m_current
{ 0 } // Assumes 0 is the first constant
127 //! Conversion constructor
128 explicit constexpr EnumerationIterator(const EnumType index
) noexcept
:
129 m_current(static_cast<IntegerType
>(index
))
132 //! Addition-assignment operator
133 constexpr EnumerationIterator
& operator+=(std::ptrdiff_t i
) noexcept
135 m_current
+= Step
* i
;
138 //! Dereference operator
139 constexpr EnumType
operator*() const noexcept
141 GMX_ASSERT(m_current
< static_cast<IntegerType
>(Last
), "dereferencing out of range");
142 return static_cast<EnumType
>(m_current
);
144 //! Difference operator
145 constexpr std::ptrdiff_t operator-(const EnumerationIterator other
) const noexcept
147 return (static_cast<std::ptrdiff_t>(m_current
) - static_cast<std::ptrdiff_t>(other
.m_current
)) / Step
;
151 IntegerType m_current
;
155 * \brief Allows constructing iterators for looping over sequential enumerators.
157 * These are particularly useful for range-based for statements.
159 * You can also provide an increment step > 1 if each constant is
160 * spaced by a larger value. Terminating constant is assumed to be a
161 * 'Count' member, which is never iterated. A different name for the
162 * terminating constant can also be specified on declaration.
164 * See file documentation for usage example.
166 * \tparam EnumType The enum (class) type.
167 * \tparam Last Last constant or number thereof (assumes a default 'Count' member).
168 * \tparam Step Step increment.
170 template<typename EnumType
, EnumType Last
= EnumType::Count
, unsigned int Step
= 1>
171 class EnumerationWrapper final
174 //! Convenience alias.
175 using IteratorType
= EnumerationIterator
<EnumType
, Last
, Step
>;
177 //! Functions required for range-based for statements to work.
179 IteratorType
begin() const { return IteratorType
{}; }
180 IteratorType
end() const { return IteratorType
{ Last
}; }
185 * \brief Wrapper for a C-style array with size and indexing defined
186 * by an enum. Useful for declaring arrays of enum names for debug
187 * or other printing. An ArrayRef<DataType> may be constructed from
188 * an object of this type.
190 * See file documentation for usage example.
192 * \tparam EnumType The enum (class) type.
193 * \tparam DataType Type of the data stored in the array.
194 * \tparam ArraySize Size in entries of the array.
196 template<typename EnumType
, // The enum (class) type.
197 typename DataType
, // Type of the data stored in the array.
198 EnumType ArraySize
= EnumType::Count
// Size in entries of the array.
200 struct EnumerationArray final
202 //! Convenience alias
203 using EnumerationWrapperType
= EnumerationWrapper
<EnumType
, ArraySize
>;
205 /*! \brief Data for names.
207 * Data is kept public so we can use direct aggregate
208 * initialization just like in a plain C-style array. */
209 DataType m_elements
[std::size_t(ArraySize
)];
211 //! Returns an object that provides iterators over the keys.
212 static constexpr EnumerationWrapperType
keys() { return EnumerationWrapperType
{}; }
213 //! Returns the size of the enumeration.
214 static constexpr std::size_t size() { return std::size_t(ArraySize
); }
217 //! Array access with asserts:
218 DataType
& operator[](const std::size_t index
)
220 GMX_ASSERT(index
< size(), "index out of range");
221 return m_elements
[index
];
223 const DataType
& operator[](const std::size_t index
) const
225 GMX_ASSERT(index
< size(), "index out of range");
226 return m_elements
[index
];
229 DataType
& operator[](const EnumType index
)
231 GMX_ASSERT(std::size_t(index
) < size(), "index out of range");
232 return m_elements
[std::size_t(index
)];
234 const DataType
& operator[](const EnumType index
) const
236 GMX_ASSERT(std::size_t(index
) < size(), "index out of range");
237 return m_elements
[std::size_t(index
)];
242 //! Range iterators (unchecked)
243 using iterator
= DataType
*;
244 using const_iterator
= const DataType
*;
245 using reverse_iterator
= std::reverse_iterator
<iterator
>;
246 using const_reverse_iterator
= std::reverse_iterator
<const_iterator
>;
250 //! Getters for forward iterators for ranges
251 iterator
begin() { return &m_elements
[0]; }
252 iterator
end() { return &m_elements
[size()]; }
253 const_iterator
begin() const { return &m_elements
[0]; }
254 const_iterator
end() const { return &m_elements
[size()]; }
258 //! Getters for reverse iterators for ranges
259 reverse_iterator
rbegin() { return reverse_iterator
{ end() }; }
260 reverse_iterator
rend() { return reverse_iterator
{ begin() }; }
261 const_reverse_iterator
rbegin() const { return const_reverse_iterator
{ end() }; }
262 const_reverse_iterator
rend() const { return const_reverse_iterator
{ begin() }; }
266 //! Pointers (unchecked)
267 using pointer
= DataType
*;
268 using const_pointer
= const DataType
*;
271 //! Returns a const raw pointer to the contents of the array.
272 const_pointer
data() const { return &m_elements
[0]; }
273 //! Returns a raw pointer to the contents of the array.
274 pointer
data() { return &m_elements
[0]; }
277 /*! \brief Returns an object that provides iterators over the keys
278 * associated with \c EnumerationArrayType.
280 * This helper function is useful in contexts where there is an object
281 * of an EnumerationArray, and we want to use a range-based for loop
282 * over the keys associated with it, and it would be inconvenient to
283 * use the very word EnumerationArray<...> type, nor introduce a using
284 * statement for this purpose. It is legal in C++ to call a static
285 * member function (such as keys()) via an object rather than the
286 * type, but clang-tidy warns about that. So instead we make available
287 * a free function that calls that static method. */
288 template<typename EnumerationArrayType
>
289 typename
EnumerationArrayType::EnumerationWrapperType
keysOf(const EnumerationArrayType
& /* arrayObject */)
291 return EnumerationArrayType::keys();