src/gromacs/utility/arrayref.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2012,2013,2014,2015, 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::ArrayRef and 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 "gromacs/utility/gmxassert.h"
  54
  55 namespace gmx
  56 {
  57
  58 /*! \brief
  59  * Tag type to initialize empty array references.
  60  *
  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.
  67  */
  68 struct EmptyArrayRef {};
  69
  70 /*! \brief
  71  * STL-like container for an interface to a C array (or part of a std::vector).
  72  *
  73  * \tparam T  Value type of elements.
  74  *
  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
  79  *    std::vector<T>).
  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.
  84  *
  85  * This class is useful for writing wrappers that expose a different view of
  86  * the internal data stored as a single vector/array.
  87  *
  88  * Methods in this class do not throw, except where indicated.
  89  *
  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.
  92  *
  93  * \todo
  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).
  97  *
  98  * \inpublicapi
  99  * \ingroup module_utility
 100  */
 101 template <typename T>
 102 class ArrayRef
 103 {
 104     public:
 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.
 120         typedef T        *pointer;
 121         //! Iterator type for the container.
 122         typedef T        *iterator;
 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;
 127
 128         /*! \brief
 129          * Constructs a reference to a particular range from two pointers.
 130          *
 131          * \param[in] begin  Pointer to the beginning of a range.
 132          * \param[in] end    Pointer to the end of a range.
 133          *
 134          * Passed pointers must remain valid for the lifetime of this object.
 135          */
 136         static ArrayRef<value_type>
 137         fromPointers(value_type *begin, value_type *end)
 138         {
 139             return ArrayRef<value_type>(begin, end);
 140         }
 141         /*! \brief
 142          * Constructs a reference to an array.
 143          *
 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.
 147          *
 148          * Passed pointer must remain valid for the lifetime of this object.
 149          */
 150         static ArrayRef<value_type>
 151         fromArray(value_type *begin, size_t size)
 152         {
 153             return ArrayRef<value_type>(begin, begin+size);
 154         }
 155         /*! \brief
 156          * Constructs a reference to a particular range in a std::vector.
 157          *
 158          * \param[in] begin  Iterator to the beginning of a range.
 159          * \param[in] end    Iterator to the end of a range.
 160          *
 161          * The referenced vector must remain valid and not be reallocated for
 162          * the lifetime of this object.
 163          */
 164         static ArrayRef<value_type>
 165         fromVector(typename std::vector<value_type>::iterator begin,
 166                    typename std::vector<value_type>::iterator end)
 167         {
 168             value_type *p_begin = (begin != end) ? &*begin : NULL;
 169             value_type *p_end   = p_begin + (end-begin);
 170             return ArrayRef<value_type>(p_begin, p_end);
 171         }
 172
 173         /*! \brief
 174          * Constructs an empty reference.
 175          */
 176         ArrayRef() : begin_(NULL), end_(NULL) {}
 177         /*! \brief
 178          * Constructs an empty reference.
 179          *
 180          * This is provided for convenience, such that EmptyArrayRef can be
 181          * used to initialize any ArrayRef, without specifying the template
 182          * type.  It is not explicit to enable that usage.
 183          */
 184         ArrayRef(const EmptyArrayRef &) : begin_(NULL), end_(NULL) {}
 185         /*! \brief
 186          * Constructs a reference to a particular range.
 187          *
 188          * \param[in] begin  Pointer to the beginning of a range.
 189          * \param[in] end    Pointer to the end of a range.
 190          *
 191          * Passed pointers must remain valid for the lifetime of this object.
 192          *
 193          * \note For clarity, use the non-member function arrayRefFromPointers
 194          * instead.
 195          */
 196         ArrayRef(pointer begin, pointer end)
 197             : begin_(begin), end_(end)
 198         {
 199             GMX_ASSERT(end >= begin, "Invalid range");
 200         }
 201         /*! \brief
 202          * Constructs a reference to a whole vector.
 203          *
 204          * \param[in] v  Vector to reference.
 205          *
 206          * Passed vector must remain valid and not be reallocated for the
 207          * lifetime of this object.
 208          *
 209          * This constructor is not explicit to allow directly passing
 210          * std::vector to a method that takes ArrayRef.
 211          */
 212         ArrayRef(std::vector<T> &v)
 213             : begin_((!v.empty()) ? &v[0] : NULL),
 214               end_((!v.empty()) ? &v[0] + v.size() : NULL)
 215         {
 216         }
 217         //! \cond
 218         // Doxygen 1.8.5 doesn't parse the declaration correctly...
 219         /*! \brief
 220          * Constructs a reference to a C array.
 221          *
 222          * \param[in] array  C array to reference.
 223          * \tparam    count  Deduced number of elements in \p array.
 224          *
 225          * This constructor can only be used with a real array (not with a
 226          * pointer).  It constructs a reference to the whole array, without
 227          * a need to pass the number of elements explicitly.  The compiler
 228          * must be able to deduce the array size.
 229          *
 230          * Passed array must remain valid for the lifetime of this object.
 231          *
 232          * This constructor is not explicit to allow directly passing
 233          * a C array to a function that takes an ArrayRef parameter.
 234          *
 235          * xlc on BG/Q compiles wrong code if the C array is a struct
 236          * field, unless value_type is char or unsigned char. There's
 237          * no good way to assert on this before C++11 (which that
 238          * compiler will never support).
 239          */
 240         template <size_t count>
 241         ArrayRef(value_type (&array)[count])
 242             : begin_(array), end_(array + count)
 243         {
 244         }
 245         //! \endcond
 246
 247         //! Returns an iterator to the beginning of the container.
 248         iterator begin() { return begin_; }
 249         //! Returns an iterator to the beginning of the container.
 250         const_iterator begin() const { return begin_; }
 251         //! Returns an iterator to the end of the container.
 252         iterator end() { return end_; }
 253         //! Returns an iterator to the end of the container.
 254         const_iterator end() const { return end_; }
 255         //! Returns an iterator to the reverse beginning of the container.
 256         iterator rbegin() { return reverse_iterator(end()); }
 257         //! Returns an iterator to the reverse beginning of the container.
 258         const_iterator rbegin() const { return reverse_iterator(end()); }
 259         //! Returns an iterator to the reverse end of the container.
 260         iterator rend() { return reverse_iterator(begin()); }
 261         //! Returns an iterator to the reverse end of the container.
 262         const_iterator rend() const { return reverse_iterator(begin()); }
 263
 264         //! Returns the size of the container.
 265         size_type size() const { return end_ - begin_; }
 266         //! Identical to size().
 267         size_type capacity() const { return end_ - begin_; }
 268         //! Whether the container is empty.
 269         bool empty() const { return begin_ == end_; }
 270
 271         //! Access container element.
 272         reference operator[](size_type n) { return begin_[n]; }
 273         //! Access container element.
 274         const_reference operator[](size_type n) const { return begin_[n]; }
 275         //! Access container element (throws on out-of-range error).
 276         reference at(size_type n)
 277         {
 278             if (n >= size())
 279             {
 280                 throw std::out_of_range("Vector index out of range");
 281             }
 282             return begin_[n];
 283         }
 284         //! Access container element (throws on out-of-range error).
 285         const_reference at(size_type n) const
 286         {
 287             if (n >= size())
 288             {
 289                 throw std::out_of_range("Vector index out of range");
 290             }
 291             return begin_[n];
 292         }
 293         //! Returns the first element in the container.
 294         reference front() { return *begin_; }
 295         //! Returns the first element in the container.
 296         const_reference front() const { return *begin_; }
 297         //! Returns the last element in the container.
 298         reference back() { return *(end_ - 1); }
 299         //! Returns the last element in the container.
 300         const_reference back() const { return *(end_ - 1); }
 301
 302         //! Returns a raw pointer to the contents of the array.
 303         pointer data() { return begin_; }
 304         //! Returns a raw pointer to the contents of the array.
 305         const_pointer data() const { return begin_; }
 306
 307         /*! \brief
 308          * Swaps referenced memory with the other object.
 309          *
 310          * The actual memory areas are not modified, only the references are
 311          * swapped.
 312          */
 313         void swap(ArrayRef<T> &other)
 314         {
 315             std::swap(begin_, other.begin_);
 316             std::swap(end_, other.end_);
 317         }
 318
 319     private:
 320         pointer           begin_;
 321         pointer           end_;
 322 };
 323
 324
 325
 326 /*! \brief
 327  * STL-like container for non-mutable interface to a C array (or part of a
 328  * std::vector).
 329  *
 330  * \tparam T  Value type of elements.
 331  *
 332  * This class provides an interface similar to \c std::vector<T>, with the
 333  * following main differences:
 334  *  - This class does not have its own storage.  Instead, it references an
 335  *    existing array of values (either a C-style array or part of an existing
 336  *    std::vector<T>).
 337  *  - Only const methods are provided to access the stored values.
 338  *    It is not possible to alter the referenced array.
 339  *  - Copying objects of this type is cheap, and the copies behave identically
 340  *    to the original object: the copy references the same set of values.
 341  *
 342  * This class is useful for writing wrappers that expose a different view of
 343  * the internal data stored as a single vector/array.
 344  *
 345  * Methods in this class do not throw, except where indicated.
 346  *
 347  * Note that due to a Doxygen limitation, the constructor that takes a C array
 348  * whose size is known at compile time does not appear in the documentation.
 349  *
 350  * \inpublicapi
 351  * \ingroup module_utility
 352  */
 353 template <typename T>
 354 class ConstArrayRef
 355 {
 356     public:
 357         //! Type of values stored in the container.
 358         typedef T         value_type;
 359         //! Type for representing size of the container.
 360         typedef size_t    size_type;
 361         //! Type for representing difference between two container indices.
 362         typedef ptrdiff_t difference_type;
 363         //! Const reference to a container element.
 364         typedef const T  &const_reference;
 365         //! Const pointer to a container element.
 366         typedef const T  *const_pointer;
 367         //! Const iterator type for the container.
 368         typedef const T  *const_iterator;
 369         //! Equal to \a const_reference since changes are not allowed.
 370         typedef const_reference reference;
 371         //! Equal to \a const_pointer since changes are not allowed.
 372         typedef const_pointer   pointer;
 373         //! Equal to \a const_iterator since changes are not allowed.
 374         typedef const_iterator  iterator;
 375         //! Standard reverse iterator.
 376         typedef std::reverse_iterator<iterator>       reverse_iterator;
 377         //! Standard reverse iterator.
 378         typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
 379
 380         //! \copydoc ArrayRef::fromPointers()
 381         static ConstArrayRef<value_type>
 382         fromPointers(const value_type *begin, const value_type *end)
 383         {
 384             return ConstArrayRef<value_type>(begin, end);
 385         }
 386         //! \copydoc ArrayRef::fromArray()
 387         static ConstArrayRef<value_type>
 388         fromArray(const value_type *begin, size_t size)
 389         {
 390             return ConstArrayRef<value_type>(begin, begin+size);
 391         }
 392         //! \copydoc ArrayRef::fromVector()
 393         static ConstArrayRef<value_type>
 394         fromVector(typename std::vector<value_type>::const_iterator begin,
 395                    typename std::vector<value_type>::const_iterator end)
 396         {
 397             const value_type *p_begin = (begin != end) ? &*begin : NULL;
 398             const value_type *p_end   = p_begin + (end-begin);
 399             return ConstArrayRef<value_type>(p_begin, p_end);
 400         }
 401
 402         /*! \brief
 403          * Constructs an empty reference.
 404          */
 405         ConstArrayRef() : begin_(NULL), end_(NULL) {}
 406         /*! \brief
 407          * Constructs an empty reference.
 408          *
 409          * This is provided for convenience, such that EmptyArrayRef can be
 410          * used to initialize any Const ArrayRef, without specifying the
 411          * template type.  It is not explicit to enable that usage.
 412          */
 413         ConstArrayRef(const EmptyArrayRef &) : begin_(NULL), end_(NULL) {}
 414         /*! \brief
 415          * Constructs a reference to a particular range.
 416          *
 417          * \param[in] begin  Pointer to the beginning of a range.
 418          * \param[in] end    Pointer to the end of a range.
 419          *
 420          * Passed pointers must remain valid for the lifetime of this object.
 421          *
 422          * \note For clarity, use the non-member function constArrayRefFromPointers
 423          * instead.
 424          */
 425         ConstArrayRef(const_pointer begin, const_pointer end)
 426             : begin_(begin), end_(end)
 427         {
 428             GMX_ASSERT(end >= begin, "Invalid range");
 429         }
 430         /*! \brief
 431          * Constructs a reference to a whole vector.
 432          *
 433          * \param[in] v  Vector to reference.
 434          *
 435          * Passed vector must remain valid and not be reallocated for the
 436          * lifetime of this object.
 437          *
 438          * This constructor is not explicit to allow directly passing
 439          * std::vector to a method that takes ConstArrayRef.
 440          */
 441         ConstArrayRef(const std::vector<T> &v)
 442             : begin_((!v.empty()) ? &v[0] : NULL),
 443               end_((!v.empty()) ? &v[0] + v.size() : NULL)
 444         {
 445         }
 446         //! \cond
 447         // Doxygen 1.8.5 doesn't parse the declaration correctly...
 448         /*! \brief
 449          * Constructs a reference to a C array.
 450          *
 451          * \param[in] array  C array to reference.
 452          * \tparam    count  Deduced number of elements in \p array.
 453          *
 454          * This constructor can only be used with a real array (not with a
 455          * pointer).  It constructs a reference to the whole array, without
 456          * a need to pass the number of elements explicitly.  The compiler
 457          * must be able to deduce the array size.
 458          *
 459          * Passed array must remain valid for the lifetime of this object.
 460          *
 461          * This constructor is not explicit to allow directly passing
 462          * a C array to a function that takes a ConstArrayRef parameter.
 463          *
 464          * xlc on BG/Q compiles wrong code if the C array is a struct
 465          * field, unless value_type is char or unsigned char. There's
 466          * no good way to assert on this before C++11 (which that
 467          * compiler will never support).
 468          */
 469         template <size_t count>
 470         ConstArrayRef(const value_type (&array)[count])
 471             : begin_(array), end_(array + count)
 472         {
 473         }
 474         //! \endcond
 475
 476         //! Returns an iterator to the beginning of the container.
 477         const_iterator begin() const { return begin_; }
 478         //! Returns an iterator to the end of the container.
 479         const_iterator end() const { return end_; }
 480         //! Returns an iterator to the reverse beginning of the container.
 481         const_iterator rbegin() const { return reverse_iterator(end()); }
 482         //! Returns an iterator to the reverse end of the container.
 483         const_iterator rend() const { return reverse_iterator(begin()); }
 484
 485         //! Returns the size of the container.
 486         size_type size() const { return end_ - begin_; }
 487         //! Identical to size().
 488         size_type capacity() const { return end_ - begin_; }
 489         //! Whether the container is empty.
 490         bool empty() const { return begin_ == end_; }
 491
 492         //! Access container element.
 493         const_reference operator[](size_type n) const { return begin_[n]; }
 494         //! Access container element (throws on out-of-range error).
 495         const_reference at(size_type n) const
 496         {
 497             if (n >= size())
 498             {
 499                 throw std::out_of_range("Vector index out of range");
 500             }
 501             return begin_[n];
 502         }
 503         //! Returns the first element in the container.
 504         const_reference front() const { return *begin_; }
 505         //! Returns the last element in the container.
 506         const_reference back() const { return *(end_ - 1); }
 507
 508         //! Returns a raw pointer to the contents of the array.
 509         const_pointer data() const { return begin_; }
 510
 511         /*! \brief
 512          * Swaps referenced memory with the other object.
 513          *
 514          * The actual memory areas are not modified, only the references are
 515          * swapped.
 516          */
 517         void swap(ConstArrayRef<T> &other)
 518         {
 519             std::swap(begin_, other.begin_);
 520             std::swap(end_, other.end_);
 521         }
 522
 523     private:
 524         const_pointer           begin_;
 525         const_pointer           end_;
 526 };
 527
 528
 529 //! \copydoc ArrayRef::fromPointers()
 530 //! \related ArrayRef
 531 template <typename T>
 532 ArrayRef<T> arrayRefFromPointers(T *begin, T *end)
 533 {
 534     return ArrayRef<T>::fromPointers(begin, end);
 535 }
 536 //! \copydoc ArrayRef::fromArray()
 537 //! \related ArrayRef
 538 template <typename T>
 539 ArrayRef<T> arrayRefFromArray(T *begin, size_t size)
 540 {
 541     return ArrayRef<T>::fromArray(begin, size);
 542 }
 543 //! \copydoc ArrayRef::fromVector()
 544 //! \related ArrayRef
 545 template <typename T>
 546 ArrayRef<T> arrayRefFromVector(typename std::vector<T>::iterator begin,
 547                                typename std::vector<T>::iterator end)
 548 {
 549     return ArrayRef<T>::fromVector(begin, end);
 550 }
 551
 552
 553 //! \copydoc ConstArrayRef::fromPointers()
 554 //! \related ConstArrayRef
 555 template <typename T>
 556 ConstArrayRef<T> constArrayRefFromPointers(const T *begin, const T *end)
 557 {
 558     return ConstArrayRef<T>::fromPointers(begin, end);
 559 }
 560 //! \copydoc ConstArrayRef::fromArray()
 561 //! \related ConstArrayRef
 562 template <typename T>
 563 ConstArrayRef<T> constArrayRefFromArray(const T *begin, size_t size)
 564 {
 565     return ConstArrayRef<T>::fromArray(begin, size);
 566 }
 567 //! \copydoc ConstArrayRef::fromVector()
 568 //! \related ConstArrayRef
 569 template <typename T>
 570 ConstArrayRef<T> constArrayRefFromVector(typename std::vector<T>::const_iterator begin,
 571                                          typename std::vector<T>::const_iterator end)
 572 {
 573     return ConstArrayRef<T>::fromVector(begin, end);
 574 }
 575
 576 /*! \brief
 577  * Simple swap method for ArrayRef objects.
 578  *
 579  * \see ArrayRef::swap()
 580  *
 581  * \ingroup module_utility
 582  */
 583 template <typename T>
 584 void swap(ArrayRef<T> &a, ArrayRef<T> &b)
 585 {
 586     a.swap(b);
 587 }
 588
 589 /*! \brief
 590  * Simple swap method for ConstArrayRef objects.
 591  *
 592  * \see ConstArrayRef::swap()
 593  *
 594  * \ingroup module_utility
 595  */
 596 template <typename T>
 597 void swap(ConstArrayRef<T> &a, ConstArrayRef<T> &b)
 598 {
 599     a.swap(b);
 600 }
 601
 602 } // namespace gmx
 603
 604 #endif