2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2012,2013,2014, 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.
37 * Declares gmx::ArrayRef and gmx::ConstArrayRef.
39 * \author Teemu Murtola <teemu.murtola@gmail.com>
41 * \ingroup module_utility
43 #ifndef GMX_UTILITY_ARRAYREF_H
44 #define GMX_UTILITY_ARRAYREF_H
53 #include "gmxassert.h"
59 * Tag type to initialize empty array references.
61 * This type (together with appropriate constructors in ArrayRef and
62 * ConstArrayRef) allows initializing any array reference to an empty value
63 * without explicitly specifying its type. This is convenient when calling
64 * a function that takes an array reference, where constructing an empty
65 * reference explicitly would otherwise require specifying the full array
66 * reference type, including the template parameter.
68 struct EmptyArrayRef {};
71 * STL-like container for an interface to a C array (or part of a std::vector).
73 * \tparam T Value type of elements.
75 * This class provides an interface similar to \c std::vector<T>, with the
76 * following main differences:
77 * - This class does not have its own storage. Instead, it references an
78 * existing array of values (either a C-style array or part of an existing
80 * - It is only possible to modify the values themselves through ArrayRef;
81 * it is not possible to add or remove values.
82 * - Copying objects of this type is cheap, and the copies behave identically
83 * to the original object: the copy references the same set of values.
85 * This class is useful for writing wrappers that expose a different view of
86 * the internal data stored as a single vector/array.
88 * Methods in this class do not throw, except where indicated.
90 * Note that due to a Doxygen limitation, the constructor that takes a C array
91 * whose size is known at compile time does not appear in the documentation.
94 * This class is not complete. At least, it should be possible to convert an
95 * ArrayRef to a ConstArrayRef. There are likely also methods missing (not
96 * required for current usage).
99 * \ingroup module_utility
101 template <typename T>
105 //! Type of values stored in the container.
106 typedef T value_type;
107 //! Type for representing size of the container.
108 typedef size_t size_type;
109 //! Type for representing difference between two container indices.
110 typedef ptrdiff_t difference_type;
111 //! Const reference to a container element.
112 typedef const T &const_reference;
113 //! Const pointer to a container element.
114 typedef const T *const_pointer;
115 //! Const iterator type for the container.
116 typedef const T *const_iterator;
117 //! Reference to a container element.
118 typedef T &reference;
119 //! Pointer to a container element.
121 //! Iterator type for the container.
123 //! Standard reverse iterator.
124 typedef std::reverse_iterator<iterator> reverse_iterator;
125 //! Standard reverse iterator.
126 typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
129 * Constructs an empty reference.
131 ArrayRef() : begin_(NULL), end_(NULL) {}
133 * Constructs an empty reference.
135 * This is provided for convenience, such that EmptyArrayRef can be
136 * used to initialize any ArrayRef, without specifying the template
137 * type. It is not explicit to enable that usage.
139 ArrayRef(const EmptyArrayRef &) : begin_(NULL), end_(NULL) {}
141 * Constructs a reference to a particular range.
143 * \param[in] begin Pointer to the beginning of a range.
144 * \param[in] end Pointer to the end of a range.
146 * Passed pointers must remain valid for the lifetime of this object.
148 * \note For clarity, use the non-member function arrayRefFromPointers
151 ArrayRef(pointer begin, pointer end)
152 : begin_(begin), end_(end)
154 GMX_ASSERT(end >= begin, "Invalid range");
157 // Doxygen 1.8.5 doesn't parse the declaration correctly...
159 * Constructs a reference to a C array.
161 * \param[in] array C array to reference.
162 * \tparam count Deduced number of elements in \p array.
164 * This constructor can only be used with a real array (not with a
165 * pointer). It constructs a reference to the whole array, without
166 * a need to pass the number of elements explicitly. The compiler
167 * must be able to deduce the array size.
169 * Passed array must remain valid for the lifetime of this object.
171 * This constructor is not explicit to allow directly passing
172 * a C array to a function that takes an ArrayRef parameter.
174 template <size_t count>
175 ArrayRef(value_type (&array)[count])
176 : begin_(array), end_(array + count)
181 //! Returns an iterator to the beginning of the container.
182 iterator begin() { return begin_; }
183 //! Returns an iterator to the beginning of the container.
184 const_iterator begin() const { return begin_; }
185 //! Returns an iterator to the end of the container.
186 iterator end() { return end_; }
187 //! Returns an iterator to the end of the container.
188 const_iterator end() const { return end_; }
189 //! Returns an iterator to the reverse beginning of the container.
190 iterator rbegin() { return reverse_iterator(end()); }
191 //! Returns an iterator to the reverse beginning of the container.
192 const_iterator rbegin() const { return reverse_iterator(end()); }
193 //! Returns an iterator to the reverse end of the container.
194 iterator rend() { return reverse_iterator(begin()); }
195 //! Returns an iterator to the reverse end of the container.
196 const_iterator rend() const { return reverse_iterator(begin()); }
198 //! Returns the size of the container.
199 size_type size() const { return end_ - begin_; }
200 //! Identical to size().
201 size_type capacity() const { return end_ - begin_; }
202 //! Whether the container is empty.
203 bool empty() const { return begin_ == end_; }
205 //! Access container element.
206 reference operator[](size_type n) { return begin_[n]; }
207 //! Access container element.
208 const_reference operator[](size_type n) const { return begin_[n]; }
209 //! Access container element (throws on out-of-range error).
210 reference at(size_type n)
214 throw std::out_of_range("Vector index out of range");
218 //! Access container element (throws on out-of-range error).
219 const_reference at(size_type n) const
223 throw std::out_of_range("Vector index out of range");
227 //! Returns the first element in the container.
228 reference front() { return *begin_; }
229 //! Returns the first element in the container.
230 const_reference front() const { return *begin_; }
231 //! Returns the last element in the container.
232 reference back() { return *(end_ - 1); }
233 //! Returns the last element in the container.
234 const_reference back() const { return *(end_ - 1); }
236 //! Returns a raw pointer to the contents of the array.
237 pointer data() { return begin_; }
238 //! Returns a raw pointer to the contents of the array.
239 const_pointer data() const { return begin_; }
242 * Swaps referenced memory with the other object.
244 * The actual memory areas are not modified, only the references are
247 void swap(ArrayRef<T> &other)
249 std::swap(begin_, other.begin_);
250 std::swap(end_, other.end_);
260 * Constructs a reference to a particular range from two pointers.
262 * \param[in] begin Pointer to the beginning of a range.
263 * \param[in] end Pointer to the end of a range.
265 * Passed pointers must remain valid for the lifetime of this object.
269 template <typename T>
270 ArrayRef<T> arrayRefFromPointers(T * begin, T * end)
272 return ArrayRef<T>(begin, end);
276 * Constructs a reference to an array
278 * \param[in] begin Pointer to the beginning of the array.
279 * May be NULL if \p size is zero.
280 * \param[in] size Number of elements in the array.
282 * Passed pointer must remain valid for the lifetime of this object.
286 template <typename T>
287 ArrayRef<T> arrayRefFromArray(T * begin, size_t size)
289 return arrayRefFromPointers<T>(begin, begin+size);
293 * Constructs a reference to a particular range in a std::vector.
295 * \param[in] begin Iterator to the beginning of a range.
296 * \param[in] end Iterator to the end of a range.
298 * The referenced vector must remain valid and not be reallocated for
299 * the lifetime of this object.
303 template <typename T>
304 ArrayRef<T> arrayRefFromVector(typename std::vector<T>::iterator begin,
305 typename std::vector<T>::iterator end)
307 T * p_begin = (begin != end) ? &*begin : NULL;
308 T * p_end = p_begin + (end-begin);
309 return arrayRefFromPointers<T>(p_begin, p_end);
315 * STL-like container for non-mutable interface to a C array (or part of a
318 * \tparam T Value type of elements.
320 * This class provides an interface similar to \c std::vector<T>, with the
321 * following main differences:
322 * - This class does not have its own storage. Instead, it references an
323 * existing array of values (either a C-style array or part of an existing
325 * - Only const methods are provided to access the stored values.
326 * It is not possible to alter the referenced array.
327 * - Copying objects of this type is cheap, and the copies behave identically
328 * to the original object: the copy references the same set of values.
330 * This class is useful for writing wrappers that expose a different view of
331 * the internal data stored as a single vector/array.
333 * Methods in this class do not throw, except where indicated.
335 * Note that due to a Doxygen limitation, the constructor that takes a C array
336 * whose size is known at compile time does not appear in the documentation.
339 * \ingroup module_utility
341 template <typename T>
345 //! Type of values stored in the container.
346 typedef T value_type;
347 //! Type for representing size of the container.
348 typedef size_t size_type;
349 //! Type for representing difference between two container indices.
350 typedef ptrdiff_t difference_type;
351 //! Const reference to a container element.
352 typedef const T &const_reference;
353 //! Const pointer to a container element.
354 typedef const T *const_pointer;
355 //! Const iterator type for the container.
356 typedef const T *const_iterator;
357 //! Equal to \a const_reference since changes are not allowed.
358 typedef const_reference reference;
359 //! Equal to \a const_pointer since changes are not allowed.
360 typedef const_pointer pointer;
361 //! Equal to \a const_iterator since changes are not allowed.
362 typedef const_iterator iterator;
363 //! Standard reverse iterator.
364 typedef std::reverse_iterator<iterator> reverse_iterator;
365 //! Standard reverse iterator.
366 typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
369 * Constructs an empty reference.
371 ConstArrayRef() : begin_(NULL), end_(NULL) {}
373 * Constructs an empty reference.
375 * This is provided for convenience, such that EmptyArrayRef can be
376 * used to initialize any Const ArrayRef, without specifying the
377 * template type. It is not explicit to enable that usage.
379 ConstArrayRef(const EmptyArrayRef &) : begin_(NULL), end_(NULL) {}
381 * Constructs a reference to a particular range.
383 * \param[in] begin Pointer to the beginning of a range.
384 * \param[in] end Pointer to the end of a range.
386 * Passed pointers must remain valid for the lifetime of this object.
388 * \note For clarity, use the non-member function constArrayRefFromPointers
391 ConstArrayRef(const_pointer begin, const_pointer end)
392 : begin_(begin), end_(end)
394 GMX_ASSERT(end >= begin, "Invalid range");
397 // Doxygen 1.8.5 doesn't parse the declaration correctly...
399 * Constructs a reference to a C array.
401 * \param[in] array C array to reference.
402 * \tparam count Deduced number of elements in \p array.
404 * This constructor can only be used with a real array (not with a
405 * pointer). It constructs a reference to the whole array, without
406 * a need to pass the number of elements explicitly. The compiler
407 * must be able to deduce the array size.
408 * Passed array must remain valid for the lifetime of this object.
410 * This constructor is not explicit to allow directly passing
411 * a C array to a function that takes a ConstArrayRef parameter.
413 template <size_t count>
414 ConstArrayRef(const value_type (&array)[count])
415 : begin_(array), end_(array + count)
420 //! Returns an iterator to the beginning of the container.
421 const_iterator begin() const { return begin_; }
422 //! Returns an iterator to the end of the container.
423 const_iterator end() const { return end_; }
424 //! Returns an iterator to the reverse beginning of the container.
425 const_iterator rbegin() const { return reverse_iterator(end()); }
426 //! Returns an iterator to the reverse end of the container.
427 const_iterator rend() const { return reverse_iterator(begin()); }
429 //! Returns the size of the container.
430 size_type size() const { return end_ - begin_; }
431 //! Identical to size().
432 size_type capacity() const { return end_ - begin_; }
433 //! Whether the container is empty.
434 bool empty() const { return begin_ == end_; }
436 //! Access container element.
437 const_reference operator[](size_type n) const { return begin_[n]; }
438 //! Access container element (throws on out-of-range error).
439 const_reference at(size_type n) const
443 throw std::out_of_range("Vector index out of range");
447 //! Returns the first element in the container.
448 const_reference front() const { return *begin_; }
449 //! Returns the last element in the container.
450 const_reference back() const { return *(end_ - 1); }
452 //! Returns a raw pointer to the contents of the array.
453 const_pointer data() const { return begin_; }
456 * Swaps referenced memory with the other object.
458 * The actual memory areas are not modified, only the references are
461 void swap(ConstArrayRef<T> &other)
463 std::swap(begin_, other.begin_);
464 std::swap(end_, other.end_);
468 const_pointer begin_;
474 * Constructs a reference to a particular range from two pointers.
476 * \param[in] begin Pointer to the beginning of a range.
477 * \param[in] end Pointer to the end of a range.
479 * Passed pointers must remain valid for the lifetime of this object.
481 * \related ConstArrayRef
483 template <typename T>
484 ConstArrayRef<T> constArrayRefFromPointers(const T * begin, const T * end)
486 return ConstArrayRef<T>(begin, end);
490 * Constructs a reference to an array.
492 * \param[in] begin Pointer to the beginning of the array.
493 * May be NULL if \p size is zero.
494 * \param[in] size Number of elements in the array.
496 * Passed pointer must remain valid for the lifetime of this object.
498 * \related ConstArrayRef
500 template <typename T>
501 ConstArrayRef<T> constArrayRefFromArray(const T * begin, size_t size)
503 return constArrayRefFromPointers<T>(begin, begin+size);
507 * Constructs a reference to a particular range in a std::vector.
509 * \param[in] begin Iterator to the beginning of a range.
510 * \param[in] end Iterator to the end of a range.
512 * The referenced vector must remain valid and not be reallocated for
513 * the lifetime of this object.
515 * \related ConstArrayRef
517 template <typename T>
518 ConstArrayRef<T> constArrayRefFromVector(typename std::vector<T>::const_iterator begin,
519 typename std::vector<T>::const_iterator end)
521 const T * p_begin = (begin != end) ? &*begin : NULL;
522 const T * p_end = p_begin + (end-begin);
523 return constArrayRefFromPointers<T>(p_begin, p_end);
527 * Simple swap method for ArrayRef objects.
529 * \see ArrayRef::swap()
531 * \ingroup module_utility
533 template <typename T>
534 void swap(ArrayRef<T> &a, ArrayRef<T> &b)
540 * Simple swap method for ConstArrayRef objects.
542 * \see ConstArrayRef::swap()
544 * \ingroup module_utility
546 template <typename T>
547 void swap(ConstArrayRef<T> &a, ConstArrayRef<T> &b)