/*! \file array_dec.h
 * \brief array class declarations (prototypes)
 * 
 * ----------------------------------------------------------------------------
 * 
 * $Id: array_dec.h,v 1.3 2002-12-10 19:56:01 forbrig Exp $
 * \author Thomas Forbriger
 * \since 08/12/2002
 * 
 * array class declarations (prototypes)
 *
 * \note
 * This should never be included directly. Use array.h or binarray.h instead.
 *
 * \todo 
 * Do we need the using directive?
 * 
 * Copyright (c) 2002 by Thomas Forbriger (IMG Frankfurt) 
 * 
 * REVISIONS and CHANGES 
 *  - 08/12/2002   V1.0   copied from libcontxx
 * 
 * ============================================================================
 */

// include guard
#ifndef AFF_ARRAY_DEC_H_VERSION

#define AFF_ARRAY_DEC_H_VERSION \
  "AFF_ARRAY_DEC_H   V1.0   "
#define AFF_ARRAY_DEC_H_CVSID \
  "$Id: array_dec.h,v 1.3 2002-12-10 19:56:01 forbrig Exp $"

#include <aff/sharedheap.h>
#include <aff/strided.h>
#include <aff/range.h>

namespace aff {

#ifdef AFF_PREBUILT
namespace prebuilt {
#endif

#ifdef CONTXX_PREBUILT
  using namespace aff::prebuilt::util;
  using namespace aff::prebuilt::shape;
  using  aff::prebuilt::representation::SharedHeap;
  using  aff::prebuilt::subscriptor::StridedRepresentation;
#else
  using namespace aff::util;
  using namespace aff::shape;
  using  aff::representation::SharedHeap;
  using  aff::subscriptor::StridedRepresentation;
#endif

  /*! \brief Full multi-dimensional array functionality.
   *
   * The array class highly depends on base classes from which inherts most of
   * its functionality. 
   * The user may select from several provided array designs through template
   * parameters:
   * \param T element type of array (passed to Subscriptor base class)
   * \param N dimensionality of array (passed to Subscriptor base class)
   * \param Representation Representation (engine for memory access) base
   *        class type (passed to Subscriptor base class)
   * \param Subscriptor Subscriptor base class type
   *
   * \sa \ref page_shapes_and_subscriptors
   * \sa \ref page_representation
   * \sa \ref sec_main_modules
   * \sa tests/arraytest.cc
   *
   * \note
   * We may just use the default copy constructor and default copy operator.
   *
   * If you want to create an array for externally managed memory (e.g. arrays
   * taken from Fortran code): First create a SharedHeap representation for the
   * given memory pointer and size. Second create a shape, defining the memory
   * layout and then create the array object from these both.
   *
   * \todo
   * documentation of class Array must be reworked
   *
   * \todo
   * class Array must be reworked itself entirely
   *
   * \todo 
   * Explain the new concept of multidimensional array indexing
   */
  template<class T>
    class Array:
      public aff::Strided, public aff::SharedHeap<T>
    {
      public:
        //! Type of representation
        typedef aff::SharedHeap<T> Trepresentation;
        //! Type of subscriptor
        typedef aff::Strided Tshape;
        //! Element type
        typedef typename Trepresentation::Tvalue Tvalue;
        //! Type of pointer to element
        typedef typename Trepresentation::Tpointer Tpointer;
        //! Type of reference to element
        typedef typename Trepresentation::Treference Treference;
        //! Type of const reference to element
        typedef typename Trepresentation::Tconst_reference Tconst_reference;
        //! Type to be used as data representation
        typedef typename Trepresentation::Tmutable_value Tmutable_value;
        //! Type to be used as element for const version
        typedef typename Trepresentation::Tconst_value Tconst_value;
        //! Type of this array
        typedef Array<T> Tcontainer;
        //! Type of the array of const values
        typedef Array<Tconst_value> Tcontainer_of_const;

        //! construct from nothing (empty)
        Array() { }
        //! construct from shape and representation
        Array(const Tshape& shape, 
              const Trepresentation& representation);
        //! construct from shape (defines size and layout)
        explicit Array(const Tshape& shape);

        //! conversion to container of const values
        operator Tcontainer_of_const() const
        {
          Tcontainer_of_const retval(*this, *this);
          return(retval);
        }

        //! by size we mean the size defined by the shape
        Tsize size(const Tsubscript& i) const
        { return(this->Tshape::size(i)); }
        //! by size we mean the size defined by the shape
        Tsize size() const
        { return(this->Tshape::size()); }
          
        //! set whole array to value
        Array& operator=(const T& value);

        //! create an identical COPY (deep copy) of this array
        Array copyout() const;

        //! COPY values (deep copy) from other array of convertible type
        //! (returns itself)
        template<class TT>
          Array& copyin(const Array<TT>& a);

    }; // class Array

#ifdef AFF_PREBUILT
} // namespace prebuilt
#endif

} // namespace aff

#ifndef AFF_NO_DEFINITIONS
#include <aff/array_def.h>
#endif

#endif // AFF_ARRAY_DEC_H_VERSION (includeguard)

/* ----- END OF array_dec.h ----- */