src/gromacs/utility/arrayref.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   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.
   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
  37  * Declares gmx::ConstArrayRef.
  38  *
  39  * \author Teemu Murtola <teemu.murtola@gmail.com>
  40  * \inpublicapi
  41  * \ingroup module_utility
  42  */
  43 #ifndef GMX_UTILITY_ARRAYREF_H
  44 #define GMX_UTILITY_ARRAYREF_H
  45
  46 #include <cstddef>
  47
  48 #include <iterator>
  49 #include <stdexcept>
  50 #include <utility>
  51 #include <vector>
  52
  53 #include "gmxassert.h"
  54
  55 namespace gmx
  56 {
  57
  58 /*! \brief
  59  * STL container non-mutable interface for a C array (or part of a std::vector).
  60  *
  61  * \tparam T  Value type of elements.
  62  *
  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
  67  *    std::vector<T>).
  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.
  72  *
  73  * This class is useful for writing wrappers that expose a different view of
  74  * the internal data stored as a single vector/array.
  75  *
  76  * Methods in this class do not throw, except where indicated.
  77  *
  78  * Note that due to a Doxygen limitation, the constructor that takes a C array
  79  * whose size is known at compile time does not appear in the documentation.
  80  *
  81  * \inpublicapi
  82  * \ingroup module_utility
  83  */
  84 template <typename T>
  85 class ConstArrayRef
  86 {
  87     public:
  88         //! Type of values stored in the container.
  89         typedef T         value_type;
  90         //! Type for representing size of the container.
  91         typedef size_t    size_type;
  92         //! Type for representing difference between two container indices.
  93         typedef ptrdiff_t difference_type;
  94         //! Const reference to a container element.
  95         typedef const T  &const_reference;
  96         //! Const pointer to a container element.
  97         typedef const T  *const_pointer;
  98         //! Const iterator type for the container.
  99         typedef const T  *const_iterator;
 100         //! Equal to \a const_reference since changes are not allowed.
 101         typedef const_reference reference;
 102         //! Equal to \a const_pointer since changes are not allowed.
 103         typedef const_pointer   pointer;
 104         //! Equal to \a const_iterator since changes are not allowed.
 105         typedef const_iterator  iterator;
 106         //! Standard reverse iterator.
 107         typedef std::reverse_iterator<iterator>       reverse_iterator;
 108         //! Standard reverse iterator.
 109         typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
 110
 111         /*! \brief
 112          * Constructs an empty reference.
 113          */
 114         ConstArrayRef() : begin_(NULL), end_(NULL) {}
 115         /*! \brief
 116          * Constructs a reference to a particular range.
 117          *
 118          * \param[in] begin  Pointer to the beginning of a range.
 119          * \param[in] end    Pointer to the end of a range.
 120          *
 121          * Passed pointers must remain valid for the lifetime of this object.
 122          */
 123         ConstArrayRef(const_pointer begin, const_pointer end)
 124             : begin_(begin), end_(end)
 125         {
 126             GMX_ASSERT(end >= begin, "Invalid range");
 127         }
 128         /*! \brief
 129          * Constructs a reference to a particular range in a std::vector.
 130          *
 131          * \param[in] begin  Iterator to the beginning of a range.
 132          * \param[in] end    Iterator to the end of a range.
 133          *
 134          * The referenced vector must remain valid and not be reallocated for
 135          * the lifetime of this object.
 136          */
 137         ConstArrayRef(typename std::vector<value_type>::const_iterator begin,
 138                       typename std::vector<value_type>::const_iterator end)
 139             : begin_((begin != end) ? &*begin : NULL),
 140               end_(begin_+(end-begin))
 141         {
 142             GMX_ASSERT(end >= begin, "Invalid range");
 143         }
 144         /*! \brief
 145          * Constructs a reference to an array.
 146          *
 147          * \param[in] begin  Pointer to the beginning of the array.
 148          *      May be NULL if \p size is zero.
 149          * \param[in] size   Number of elements in the array.
 150          *
 151          * Passed pointer must remain valid for the lifetime of this object.
 152          */
 153         ConstArrayRef(const_pointer begin, size_type size)
 154             : begin_(begin), end_(begin + size)
 155         {
 156         }
 157         //! \cond
 158         // Doxygen 1.8.5 doesn't parse the declaration correctly...
 159         /*! \brief
 160          * Constructs a reference to a C array.
 161          *
 162          * \param[in] array  C array to reference.
 163          * \tparam    count  Deduced number of elements in \p array.
 164          *
 165          * This constructor can only be used with a real array (not with a
 166          * pointer).  It constructs a reference to the whole array, without
 167          * a need to pass the number of elements explicitly.  The compiler
 168          * must be able to deduce the array size.
 169          * Passed array must remain valid for the lifetime of this object.
 170          *
 171          * This constructor is not explicit to allow directly passing
 172          * a C array to a function that takes a ConstArrayRef parameter.
 173          */
 174         template <size_t count>
 175         ConstArrayRef(const value_type (&array)[count])
 176             : begin_(array), end_(array + count)
 177         {
 178         }
 179         //! \endcond
 180
 181         //! Returns an interator to the beginning of the container.
 182         const_iterator begin() const { return begin_; }
 183         //! Returns an interator to the end of the container.
 184         const_iterator end() const { return end_; }
 185         //! Returns an interator to the reverse beginning of the container.
 186         const_iterator rbegin() const { return reverse_iterator(end()); }
 187         //! Returns an interator to the reverse end of the container.
 188         const_iterator rend() const { return reverse_iterator(begin()); }
 189
 190         //! Returns the size of the container.
 191         size_type size() const { return end_ - begin_; }
 192         //! Identical to size().
 193         size_type capacity() const { return end_ - begin_; }
 194         //! Whether the container is empty.
 195         bool empty() const { return begin_ == end_; }
 196
 197         //! Access container element.
 198         const_reference operator[](size_type n) const { return begin_[n]; }
 199         //! Access container element (throws on out-of-range error).
 200         const_reference at(size_type n) const
 201         {
 202             if (n >= size())
 203             {
 204                 throw std::out_of_range("Vector index out of range");
 205             }
 206             return begin_[n];
 207         }
 208         //! Returns the first element in the container.
 209         const_reference front() const { return *begin_; }
 210         //! Returns the last element in the container.
 211         const_reference back() const { return *(end_ - 1); }
 212
 213         //! Returns a raw pointer to the contents of the array.
 214         const_pointer data() const { return begin_; }
 215
 216         /*! \brief
 217          * Swaps referenced memory with the other object.
 218          *
 219          * The actual memory areas are not modified, only the references are
 220          * swapped.
 221          */
 222         void swap(ConstArrayRef<T> &other)
 223         {
 224             std::swap(begin_, other.begin_);
 225             std::swap(end_, other.end_);
 226         }
 227
 228     private:
 229         const_pointer           begin_;
 230         const_pointer           end_;
 231 };
 232
 233 /*! \brief
 234  * Simple swap method for ConstArrayRef objects.
 235  *
 236  * \see ConstArrayRef::swap()
 237  *
 238  * \ingroup module_utility
 239  */
 240 template <typename T>
 241 void swap(ConstArrayRef<T> &a, ConstArrayRef<T> &b)
 242 {
 243     a.swap(b);
 244 }
 245
 246 } // namespace gmx
 247
 248 #endif