M/c++_api/inc/DM/Array.hpp

#pragma once
 
#include "DM/config.hpp"
#include "DM/AutoLink.hpp" //enable autolink
 
// std::ptrdiff_t and std::size_t
//#include <cstddef>
// std::reverse_iterator<Iterator>
//#include <iterator>
// std::out_of_range
#include <stdexcept>
 
 
DM_NAMESPACE_BEGIN
 
  /**
  \class  Array
  \tparam T the element type
  \tparam N the constant size, must be >= 1
 
  \brief a template class holding a C-array of constant size.
 
  \author wk
  \date   03.02.2011
 
  Array is an aggregate, meaning that it may be initialized with a static initializer list:
    opals::Array<double,3> arr = { 1., 2., 3. };
    Array fulfills almost all the requirements of an STL reversible container.
    The complete implementation is exposed, why opals users may instantiate Array<T,N> with arbitrary template arguments.
    The class closely follows boost::array.
  \internal
  opals::Array extends boost::array. Like boost::array, opals::Array is an aggregate,
  as it defines no constructors and no protected/private data members (and no base class, no virtual functions).
  As a consequence, opals::Array may be initialized with an initializer list,
    but no conversion constructor from boost::array can be provided.
  For that purpose, first instantiate the opals::Array, then assign the boost::array:
    opals::Array<double,2> arr;
    arr = boost_array_double_2_instance;
  As extensions to boost::array, assignment of a C-array is supported:
    double da[] = { 1., 2. };
    arr = da;
  In contrast to opals::Vector and opals::List,
   its data member is a plain-old-C-array,
   why the whole implementation can be exposed to DLL users, together with
   global template comparison operators - mind that the C-array
   must not be protected/private in order to keep Array an aggregate.
  As further extensions to the interface of boost::array,
  opals::Array provides operator<<, operator>>,
  and function toInternal(),
  which returns a boost::array<U>, where U is the internal type
  corresponding to T (see InternalType).
  In contrast to boost::array, Array may not be instantiated for N==0.
  */
 
  template<class T, std::size_t N>
  class DM_API Array
  {
 
  public:
 
    T elems[N];    // fixed-size C-array of elements of type T
 
    // type definitions
    typedef T              value_type;
    typedef T*             iterator;
    typedef const T*       const_iterator;
    typedef T&             reference;
    typedef const T&       const_reference;
    typedef std::size_t    size_type;
    typedef std::ptrdiff_t difference_type;
    typedef std::reverse_iterator<iterator>       reverse_iterator;
    typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
    enum { static_size = N };
 
    
    /// \name assignment, swapping
    //@{
    /// assignment with type conversion
    template <typename T2>
    Array<T,N>& operator= (const Array<T2,N> &other)
    {
      ::std::copy(other.begin(),other.end(), begin());
      return *this;
    }
    /// assign a C-array with type conversion
    template <typename T2>
    Array<T,N>& operator= ( const T2 (&other) [N] )
    {
      std::copy(other,&other[N], begin());
      return *this;
    }
    
    /// assign one value to all elements
    void assign(const T &val)
    { std::fill_n(begin(),size(),val); }
    
    /// swap (linear complexity)
    void swap(Array<T,N> &other)
    { std::swap_ranges(begin(),end(),other.begin()); }
    //}@
 
    /// \name iterator traversal
    /// forward/reverse, const/non-const
    //@{
    iterator       begin()       { return elems; }
    const_iterator begin() const { return elems; }
    iterator       end()         { return elems+N; }
    const_iterator end()   const { return elems+N; }
 
    reverse_iterator       rbegin()       { return reverse_iterator(end()); }
    const_reverse_iterator rbegin() const { return const_reverse_iterator(end()); }
    reverse_iterator       rend()         { return reverse_iterator(begin()); }
    const_reverse_iterator rend()   const { return const_reverse_iterator(begin()); }
    //}@
 
    /// \name direct element access with range check
    /// zero-based indexing
    //@{
    reference       operator[](size_type i)       { rangecheck(i); return elems[i]; }
    const_reference operator[](size_type i) const { rangecheck(i); return elems[i]; }
    reference       at(size_type i)               { rangecheck(i); return elems[i]; }
    const_reference at(size_type i) const         { rangecheck(i); return elems[i]; }
    //}@
 
 
    /// \name first/last element
    //@{
    reference       front()       { return elems[0];  }
    const_reference front() const { return elems[0]; }
    reference       back()        { return elems[N-1];  }
    const_reference back()  const { return elems[N-1]; }
    //}@
 
    /// \name direct access to C-array
    //@{
    const T* data() const { return elems; }
    T*       data()       { return elems; }
    T*       c_array()    { return elems; }
    //}@
 
    /// \name size
    //@{
    static size_type size()     { return N; }
    static bool      empty()    { return false; }
    static size_type max_size() { return N; }
    //}@
 
  private:
    static void rangecheck (size_type i)
    {
      if (i >= size()) {
        throw std::out_of_range("Array<>: index out of range");
      }
    }
  };
 
  template<class T>
  class Array<T,0>
  {
    template<class U> struct Must_not_instantiate_an_empty_opals_Array;
    typedef typename Must_not_instantiate_an_empty_opals_Array<T>::Type CompilationError;
  };
 
  /// \relatesalso Array
  template<class T, std::size_t N>
  bool operator== (const Array<T,N>& l, const Array<T,N>& r) {
    return std::equal(l.begin(), l.end(), r.begin());
  }
 
  /// \relatesalso Array
  template<class T, std::size_t N>
  bool operator< (const Array<T,N>& l, const Array<T,N>& r) {
    return std::lexicographical_compare(l.begin(),l.end(),r.begin(),r.end());
  }
 
  /// \relatesalso Array
  template<class T, std::size_t N>
  bool operator!= (const Array<T,N>& l, const Array<T,N>& r) {
    return !(l==r);
  }
 
  /// \relatesalso Array
  template<class T, std::size_t N>
  bool operator> (const Array<T,N>& l, const Array<T,N>& r) {
    return r<l;
  }
 
  /// \relatesalso Array
  template<class T, std::size_t N>
  bool operator<= (const Array<T,N>& l, const Array<T,N>& r) {
    return !(r<l);
  }
 
  /// \relatesalso Array
  template<class T, std::size_t N>
  bool operator>= (const Array<T,N>& l, const Array<T,N>& r) {
    return !(l<r);
  }
  
  /// \relatesalso Array
  template<class T, std::size_t N>
  void swap (Array<T,N>& l, Array<T,N>& r) {
    l.swap(r);
  }
 
DM_NAMESPACE_END