2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2012,2013, by the GROMACS development team, led by
5 * David van der Spoel, Berk Hess, Erik Lindahl, and including many
6 * others, as listed in the AUTHORS file in the top-level source
7 * 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::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 * STL container non-mutable interface for a C array (or part of a std::vector).
61 * \tparam T Value type of elements.
63 * This class provides an interface similar to \c std::vector<T>, with the
64 * following main differences:
65 * - This class does not have its own storage. Instead, it references an
66 * existing array of values (either a C-style array or part of an existing
68 * - Only const methods are provided to access the stored values.
69 * It is not possible to alter the referenced array.
70 * - Copying objects of this type is cheap, and the copies behave identically
71 * to the original object: the copy references the same set of values.
73 * This class is useful for writing wrappers that expose a different view of
74 * the internal data stored as a single vector/array.
76 * Methods in this class do not throw, except where indicated.
79 * \ingroup module_utility
85 //! Type of values stored in the container.
87 //! Type for representing size of the container.
88 typedef size_t size_type;
89 //! Type for representing difference between two container indices.
90 typedef ptrdiff_t difference_type;
91 //! Const reference to a container element.
92 typedef const T &const_reference;
93 //! Const pointer to a container element.
94 typedef const T *const_pointer;
95 //! Const iterator type for the container.
96 typedef const T *const_iterator;
97 //! Equal to \a const_reference since changes are not allowed.
98 typedef const_reference reference;
99 //! Equal to \a const_pointer since changes are not allowed.
100 typedef const_pointer pointer;
101 //! Equal to \a const_iterator since changes are not allowed.
102 typedef const_iterator iterator;
103 //! Standard reverse iterator.
104 typedef std::reverse_iterator<iterator> reverse_iterator;
105 //! Standard reverse iterator.
106 typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
109 * Constructs an empty reference.
111 ConstArrayRef() : begin_(NULL), end_(NULL) {}
113 * Constructs a reference to a particular range.
115 * \param[in] begin Pointer to the beginning of a range.
116 * \param[in] end Pointer to the end of a range.
118 * Passed pointers must remain valid for the lifetime of this object.
120 ConstArrayRef(const_pointer begin, const_pointer end)
121 : begin_(begin), end_(end)
123 GMX_ASSERT(end >= begin, "Invalid range");
126 * Constructs a reference to a particular range in a std::vector.
128 * \param[in] begin Iterator to the beginning of a range.
129 * \param[in] end Iterator to the end of a range.
131 * The referenced vector must remain valid and not be reallocated for
132 * the lifetime of this object.
134 ConstArrayRef(typename std::vector<T>::const_iterator begin,
135 typename std::vector<T>::const_iterator end)
136 : begin_((begin != end) ? &*begin : NULL),
137 end_(begin_+(end-begin))
139 GMX_ASSERT(end >= begin, "Invalid range");
142 * Constructs a reference to an array.
144 * \param[in] begin Pointer to the beginning of the array.
145 * May be NULL if \p size is zero.
146 * \param[in] size Number of elements in the array.
148 * Passed pointer must remain valid for the lifetime of this object.
150 ConstArrayRef(const_pointer begin, size_type size)
151 : begin_(begin), end_(begin + size)
155 //! Returns an interator to the beginning of the container.
156 const_iterator begin() const { return begin_; }
157 //! Returns an interator to the end of the container.
158 const_iterator end() const { return end_; }
159 //! Returns an interator to the reverse beginning of the container.
160 const_iterator rbegin() const { return reverse_iterator(end()); }
161 //! Returns an interator to the reverse end of the container.
162 const_iterator rend() const { return reverse_iterator(begin()); }
164 //! Returns the size of the container.
165 size_type size() const { return end_ - begin_; }
166 //! Identical to size().
167 size_type capacity() const { return end_ - begin_; }
168 //! Whether the container is empty.
169 bool empty() const { return begin_ == end_; }
171 //! Access container element.
172 const_reference operator[](size_type n) const { return begin_[n]; }
173 //! Access container element (throws on out-of-range error).
174 const_reference at(size_type n) const
178 throw std::out_of_range("Vector index out of range");
182 //! Returns the first element in the container.
183 const_reference front() const { return *begin_; }
184 //! Returns the last element in the container.
185 const_reference back() const { return *(end_ - 1); }
187 //! Returns a raw pointer to the contents of the array.
188 const_pointer data() const { return begin_; }
191 * Swaps referenced memory with the other object.
193 * The actual memory areas are not modified, only the references are
196 void swap(ConstArrayRef<T> &other)
198 std::swap(begin_, other.begin_);
199 std::swap(end_, other.end_);
203 const_pointer begin_;
208 * Simple swap method for ConstArrayRef objects.
210 * \see ConstArrayRef::swap()
212 * \ingroup module_utility
214 template <typename T>
215 void swap(ConstArrayRef<T> &a, ConstArrayRef<T> &b)