Domi
Multi-dimensional, distributed data structures
 All Classes Files Functions Variables Typedefs Friends
Related Functions | List of all members
Domi::MDArray< T > Class Template Reference

Memory-safe templated multi-dimensional array class. More...

#include <Domi_MDArray.hpp>

Public Types

Public types
typedef T value_type
 Value type.
 
typedef T * pointer
 Pointer type.
 
typedef const T * const_pointer
 Const pointer type.
 
typedef T & reference
 Reference type.
 
typedef const T & const_reference
 Const reference type.
 

Public Member Functions

Constructors and Destructor
 MDArray ()
 Default constructor. More...
 
 MDArray (const Teuchos::ArrayView< dim_type > &dims)
 Constructor with dimensions only. More...
 
 MDArray (const Teuchos::ArrayView< dim_type > &dims, const T &value, const Layout layout=DEFAULT_ORDER)
 Constructor with dimensions and default value, with optional storage order. More...
 
 MDArray (const Teuchos::ArrayView< dim_type > &dims, const Layout layout, const T &value=value_type())
 Constructor with dimensions and storage order, with optional default value. More...
 
 MDArray (const MDArray< T > &source)
 Copy constructor. More...
 
 MDArray (const MDArrayView< T > &source)
 Copy constructor from MDArrayView More...
 
 ~MDArray ()
 Destructor.
 
Attribute accessor methods
int numDims () const
 Return the number of dimensions.
 
const Teuchos::Array< dim_type > & dimensions () const
 Return an array of dimensions.
 
dim_type dimension (int axis) const
 Return the dimension of the given axis. More...
 
size_type size () const
 Return the total size of the MDArray
 
const Teuchos::Array< size_type > & strides () const
 Return the indexing strides.
 
const Teuchos::Array< T > & array () const
 Return the underlying Teuchos::Array
 
const Layout layout () const
 Return the storage order.
 
Conversions to MDArrayView
MDArrayView< T > mdArrayView ()
 Perform an explicit conversion to a non-const MDArrayView<T>
 
const MDArrayView< T > mdArrayView () const
 Perform an explicit conversion to a const MDArrayView<T>
 
MDArrayView< const T > mdArrayViewConst ()
 Perform an explicit conversion to a non-const MDArrayView<const T>
 
const MDArrayView< const T > mdArrayViewConst () const
 Perform an explicit conversion to a const MDArrayView<const T>
 
 operator MDArrayView< T > () const
 Perform an implicit conversion to a non-const MDArrayView
 
 operator MDArrayView< const T > () const
 Perform an implicit conversion to a const MDArrayView
 
Indexing operators that return <tt>MDArrayView</tt>s
MDArrayView< T > operator[] (dim_type i)
 Sub-array access operator. The returned MDArrayView object will have one fewer dimensions than the calling MDArray. More...
 
const MDArrayView< T > operator[] (dim_type i) const
 Sub-array const access operator. The returned MDArrayView object will have one fewer dimensions than the calling MDArray. More...
 
MDArrayView< T > operator[] (Slice s)
 Sub-array access operator. The returned MDArrayView object will have the same number of dimensions as the calling MDArray. More...
 
const MDArrayView< T > operator[] (Slice s) const
 Sub-array const access operator. The returned MDArrayView object will have the same number of dimensions as the calling MDArray. More...
 
MDArrayView< T > operator() ()
 Conversion to non-const MDArrayView
 
const MDArrayView< T > operator() () const
 Conversion to const MDArrayView
 
Indexing operators that return a reference to a single

array element

T & operator() (dim_type i)
 Non-const 1D element access operator. More...
 
T & operator() (dim_type i, dim_type j)
 Non-const 2D element access operator. More...
 
T & operator() (dim_type i, dim_type j, dim_type k)
 Non-const 3D element access operator. More...
 
T & operator() (dim_type i, dim_type j, dim_type k, dim_type m)
 Non-const 4D element access operator. More...
 
T & operator() (dim_type i, dim_type j, dim_type k, dim_type m, dim_type n)
 Non-const 5D element access operator. More...
 
T & operator() (dim_type i, dim_type j, dim_type k, dim_type m, dim_type n, dim_type p,...)
 Non-const 6D and higher element access operator. More...
 
const T & operator() (dim_type i) const
 Const 1D element access operator. More...
 
const T & operator() (dim_type i, dim_type j) const
 Const 2D element access operator. More...
 
const T & operator() (dim_type i, dim_type j, dim_type k) const
 Const 3D element access operator. More...
 
const T & operator() (dim_type i, dim_type j, dim_type k, dim_type m) const
 Const 4D element access operator. More...
 
const T & operator() (dim_type i, dim_type j, dim_type k, dim_type m, dim_type n) const
 Const 5D element access operator. More...
 
const T & operator() (dim_type i, dim_type j, dim_type k, dim_type m, dim_type n, dim_type p,...) const
 Const 6D and higher element access operator. More...
 

Friends

Non-member operators and functions
template<typename T2 >
bool operator== (const MDArray< T2 > &a1, const MDArray< T2 > &a2)
 Equality operator.
 
template<typename T2 >
bool operator== (const MDArray< T2 > &a1, const MDArrayView< T2 > &a2)
 MDArray/MDArrayView equality operator.
 
template<typename T2 >
bool operator== (const MDArrayView< T2 > &a1, const MDArray< T2 > &a2)
 MDArrayView/MDArray equality operator.
 
template<typename T2 >
bool operator!= (const MDArray< T2 > &a1, const MDArray< T2 > &a2)
 Inequality operator.
 
template<typename T2 >
bool operator!= (const MDArray< T2 > &a1, const MDArrayView< T2 > &a2)
 MDArray/MDArrayView inequality operator.
 
template<typename T2 >
bool operator!= (const MDArrayView< T2 > &a1, const MDArray< T2 > &a2)
 MDArrayView/MDArray inequality operator.
 
template<typename T2 >
std::ostream & operator<< (std::ostream &os, const MDArray< T2 > &a)
 Stream output operator.
 
template<typename T2 >
void swap (MDArray< T2 > &a1, MDArray< T2 > &a2)
 Swap function.
 

Related Functions

(Note that these are not member functions.)

template<typename T >
bool operator== (const MDArray< T > &a1, const MDArray< T > &a2)
 Equality operator.
 
template<typename T >
bool operator!= (const MDArray< T > &a1, const MDArray< T > &a2)
 Inequality operator.
 
template<typename T >
bool operator!= (const MDArray< T > &a1, const MDArrayView< T > &a2)
 MDArrayView inequality operator.
 
template<typename T >
void swap (MDArray< T > &a1, MDArray< T > &a2)
 Non-member swap.
 
template<typename T >
void swap (MDArrayView< T > &a1, MDArrayView< T > &a2)
 Non-member swap.
 

Iterator classes and methods

typedef MDIterator< MDArray< T > > iterator
 
typedef MDIterator< MDArray
< const T > > 
const_iterator
 
typedef MDRevIterator< MDArray
< T > > 
reverse_iterator
 
typedef MDRevIterator< MDArray
< const T > > 
const_reverse_iterator
 
class MDIterator< MDArray< T > >
 
class MDIterator< MDArray< const T > >
 
class MDRevIterator< MDArray< T > >
 
class MDRevIterator< MDArray< const T > >
 
iterator begin ()
 Return the beginning iterator.
 
iterator end ()
 Return the ending iterator.
 
const_iterator begin () const
 Return the beginning const_iterator.
 
const_iterator end () const
 Return the ending const_iterator.
 
const_iterator cbegin () const
 Return the beginning const_iterator.
 
const_iterator cend () const
 Return the ending const_iterator.
 
reverse_iterator rbegin ()
 Return the beginning reverse_iterator.
 
reverse_iterator rend ()
 Return the ending reverse_iterator.
 
const_reverse_iterator crbegin () const
 Return the beginning const_reverse_iterator.
 
const_reverse_iterator crend () const
 Return the ending const_reverse_iterator.
 

Teuchos::Array-like and std::vector-like methods

void assign (const T &value)
 Assign a value to all elements of the MDArray More...
 
T & at (dim_type i,...)
 Non-const single element access method with bounds checking. More...
 
const T & at (dim_type i,...) const
 Const single element access method with bounds checking. More...
 
size_type capacity () const
 Return the capacity of the underlying Teuchos::Array
 
void clear ()
 Clear the MDArray
 
bool empty () const
 Return whether the MDArray is empty.
 
size_type max_size () const
 Return the maximum allowable size for the MDArray
 
void resize (const Teuchos::ArrayView< dim_type > &dims)
 Resize the MDArray based on the given dimensions. More...
 
void swap (MDArray< T > &a)
 Swap this MDArray with the given MDArray
 
std::string toString () const
 Convert the MDArray to a string representation.
 
const T * getRawPtr () const
 Return a const raw pointer to the beginning of the MDArray or NULL if unsized.
 
T * getRawPtr ()
 Return a raw pointer to the beginning of the MDArray or NULL if unsized.
 
static bool hasBoundsChecking ()
 Return true if MDArray has been compiled with bounds checking on.
 

Detailed Description

template<typename T>
class Domi::MDArray< T >

Memory-safe templated multi-dimensional array class.

MDArray Design Discussion

The purpose of the MDArray class is to provide multi-dimensional array storage for an arbitrary number of dimensions. It stores a Teuchos::Array as member data to provide its data buffer and so adopts all of the memory safety of the Teuchos::Array class. Storage order can be set by the user to be "C" ordering or "Fortran" ordering (C-ordering is also known as row-major or last-index-fastest; Fortran-ordering is also known as column-major or first-index-fastest). If not specified, the default is Fortran ordering.

The MDArray class also provides efficient indexing of the form a(i,j,k,...), regardless of storage order. Here, i,j,k must all be ordinals of type dim_type, and the return type is T &, where T is the type of data stored in the array.

The square bracket operator, for which the C++ standard requires one and only one argument, can take a dim_type ordinal or a Slice struct and always returns an MDArrayView object. Providing a Slice argument (where a Slice contains a start index, a stop index, and a step interval) will return an MDArrayView object with the same number of dimensions. Providing a dim_type argument will return an MDArrayView object with one fewer dimensions. It is possible to mix ordinal indexes and slice indexes by repeatedly using the square bracket operator. For example, if MDArray a is 3-dimensional, a[Slice()][5][4] would return a 1-dimensional MDArrayView which is all values of index i at j=5 and k=4. Note that the default Slice() object represents a full range. Note also that since the square bracket operator always returns an MDArrayView, that a[i][j][k] would return an MDArrayView<T> of one dimension of length 1, not a T&. So in this case, what is probably desired is a(i,j,k).

MDArray Construction

All MDArray constructors allocate new memory. (To construct an array that points to a view of existing memory, use the MDArrayView class.) Each constructor needs to know the number of dimensions and the length of each dimension. This is provided by a Teuchos::ArrayView object whose size is the number of dimensions and whose values are the lengths of each of those dimensions. A common and convenient way to provide a Teuchos::ArrayView object to MDArray constructors is with the overloaded Teuchos::tuple non-member constructor functions. For example, to construct an integer array with dimensions (5,6,7), you can use

MDArray<int> a(Teuchos::tuple(5,6,7));

There are various other optional arguments that can be passed to the MDArray constructors. These include a flag for storage order, of enumerated type Layout, and a default fill value of type T.

MDArray Indexing

An introductory discussion of the indexing is provided above. Here we provide more details to help users and developers understand some of the mechanics.

Since the compiler does not know the dimension of any given MDArray, the operators to access a single element of the MDArray originally took the following forms:

T & operator()(dim_type i, ...);
const T & operator()(dim_type i, ...);

Functions and methods that take arbitrary arguments denoted by the ellipsis ("...") are called "variadic", and unfortunately, they reduce the amount of error checking that can be done, even with HAVE_DOMI_ARRAY_BOUNDSCHECK defined. The reason for this is that the macros provided in C/C++ to handle variadic arguments do not provide a way to count the number of arguments provided. If you provide too many indexes, the excess are just ignored. If you provide too few, the behavior is undefined. Processing the variadic arguments also introduces computational overhead, so operator() has been overloaded to accept concrete numbers of indexes:

T & operator()(dim_type i);
T & operator()(dim_type i, dim_type j);
T & operator()(dim_type i, dim_type j, dim_type k);
//...
const T & operator()(dim_type i);
const T & operator()(dim_type i, dim_type j);
const T & operator()(dim_type i, dim_type j, dim_type k);
//...

These specific overloads are provided for up to five dimensions. For six dimensions and higher, a variadic argument is used. This provides both greater efficiency and bounds checking (when enebaled) for five dimensions or less. If bounds checking is off, or an array has more than five dimensions, the expectation is that if you construct an MDArray of n dimensions, then you will call operator() with n indexes, because no error wll be reported.

The offset represented by a set of indexes is computed by maintaining an internal array of stride lengths, called _strides. These are initialized such that (say, for the case of a three dimensional array) a(i,j,k) will compute offset

i * _strides[0] + j * _strides[1] + k * _strides[2]

This supplies sufficient flexibility to support both C and Fortran storage orders, simply by computing the stride lengths correctly. It also allows for correct indexing into sub-arrays. The stride values cannot be changed external to the class, but you can request a reference to their values with the

const Teuchos::Array< size_type > & strides() const

method.

The remaining operator[] indexing operators each return an MDArrayView object with a view into the calling MDArray. The operator[](dim_type) operator returns an MDArrayView object with one fewer dimensions. The operator[](Slice) operator returns an MDArrayView object with the same number of dimensions, but with a sub-view into the calling MDArray. Which axis provides the sub-view requires a little explanation.

Suppose we set b = a[Slice]. We expect b to be an MDArrayView with the same number of dimensions as a, but with a sub-view of the first axis. Logically, we would expect b[Slice] to also be a subview of the first axis. However, this is equivalent to a[Slice][Slice], and in this case we would expect that the second square brack would reference a sub-view of the second axis. In order to make a[Slice][Slice] work the way we would expect, we have to store a private "next axis" data member, and update it appropriately as square bracket operators are applied. This means that the b[Slice] example above would actually refer to the second axis, not the first. For this reason, it is strongly suggested that when indexing an n-dimensional MDArray with the square bracket operator, always chain together n square brackets, which will reset the internal "next axis" data member to the expected value of zero.

Constructor & Destructor Documentation

template<typename T >
Domi::MDArray< T >::MDArray ( )
inline

Default constructor.

Produces and MDArray with one dimension of length 0.

template<typename T >
Domi::MDArray< T >::MDArray ( const Teuchos::ArrayView< dim_type > &  dims)
inline

Constructor with dimensions only.

Parameters
dims[in] An array that defines the lengths of each dimension. The most convenient way to specify dimensions is with a Teuchos::Tuple returned by the non-member Teuchos::tuple<T>() function.
template<typename T>
Domi::MDArray< T >::MDArray ( const Teuchos::ArrayView< dim_type > &  dims,
const T &  value,
const Layout  layout = DEFAULT_ORDER 
)
inline

Constructor with dimensions and default value, with optional storage order.

Parameters
dims[in] An array that defines the lengths of each dimension. The most convenient way to specify dimensions is with a Teuchos::Tuple returned by the non-member Teuchos::tuple<T>() function.
value[in] The default value for filling the MDArray
layout[in] An enumerated value specifying the internal storage order of the MDArray
template<typename T>
Domi::MDArray< T >::MDArray ( const Teuchos::ArrayView< dim_type > &  dims,
const Layout  layout,
const T &  value = value_type() 
)
inline

Constructor with dimensions and storage order, with optional default value.

Parameters
dims[in] An array that defines the lengths of each dimension. The most convenient way to specify dimensions is with a Teuchos::Tuple returned by the non-member Teuchos::tuple<T>() function.
layout[in] An enumerated value specifying the internal storage order of the MDArray
value[in] The default value for filling the MDArray
template<typename T>
Domi::MDArray< T >::MDArray ( const MDArray< T > &  source)
inline

Copy constructor.

Parameters
source[in] The source MDArray to be copied
template<typename T>
Domi::MDArray< T >::MDArray ( const MDArrayView< T > &  source)

Copy constructor from MDArrayView

Parameters
source[in] The source MDArrayView to be copied

Member Function Documentation

template<typename T>
void Domi::MDArray< T >::assign ( const T &  value)

Assign a value to all elements of the MDArray

Parameters
value[in] The value to be assigned
template<typename T >
T & Domi::MDArray< T >::at ( dim_type  i,
  ... 
)

Non-const single element access method with bounds checking.

Parameters
i,...[in] Indexes representing the location of the single element of the MDArray to be accessed. Note that this method assumes that the user will provide the same number of arguments as the number of dimensions of the MDArray.
template<typename T >
const T & Domi::MDArray< T >::at ( dim_type  i,
  ... 
) const

Const single element access method with bounds checking.

Parameters
i,...[in] Indexes representing the location of the single element of the MDArray to be accessed. Note that this method assumes that the user will provide the same number of arguments as the number of dimensions of the MDArray.
template<typename T >
dim_type Domi::MDArray< T >::dimension ( int  axis) const
inline

Return the dimension of the given axis.

Parameters
axis[in] The axis being queried (0 for the first axis, 1 for the second axis, and so forth)
template<typename T >
T & Domi::MDArray< T >::operator() ( dim_type  i)
inline

Non-const 1D element access operator.

Parameters
i[in] 1D index.

This operator should only be used with a 1D MDArray. If HAVE_DOMI_ARRAY_BOUNDSCHECK is true and the MDArray is not 1D, an exception will be thrown.

template<typename T >
T & Domi::MDArray< T >::operator() ( dim_type  i,
dim_type  j 
)
inline

Non-const 2D element access operator.

Parameters
i[in] first 2D index.
j[in] second 2D index.

This operator should only be used with a 2D MDArray. If HAVE_DOMI_ARRAY_BOUNDSCHECK is true and the MDArray is not 2D, an exception will be thrown.

template<typename T >
T & Domi::MDArray< T >::operator() ( dim_type  i,
dim_type  j,
dim_type  k 
)
inline

Non-const 3D element access operator.

Parameters
i[in] first 3D index.
j[in] second 3D index.
k[in] third 3D index.

This operator should only be used with a 3D MDArray. If HAVE_DOMI_ARRAY_BOUNDSCHECK is true and the MDArray is not 3D, an exception will be thrown.

template<typename T >
T & Domi::MDArray< T >::operator() ( dim_type  i,
dim_type  j,
dim_type  k,
dim_type  m 
)
inline

Non-const 4D element access operator.

Parameters
i[in] first 4D index.
j[in] second 4D index.
k[in] third 4D index.
m[in] fourth 4D index.

This operator should only be used with a 4D MDArray. If HAVE_DOMI_ARRAY_BOUNDSCHECK is true and the MDArray is not 4D, an exception will be thrown.

template<typename T >
T & Domi::MDArray< T >::operator() ( dim_type  i,
dim_type  j,
dim_type  k,
dim_type  m,
dim_type  n 
)
inline

Non-const 5D element access operator.

Parameters
i[in] first 5D index.
j[in] second 5D index.
k[in] third 5D index.
m[in] fourth 5D index.
n[in] fifth 5D index.

This operator should only be used with a 5D MDArray. If HAVE_DOMI_ARRAY_BOUNDSCHECK is true and the MDArray is not 5D, an exception will be thrown.

template<typename T >
T & Domi::MDArray< T >::operator() ( dim_type  i,
dim_type  j,
dim_type  k,
dim_type  m,
dim_type  n,
dim_type  p,
  ... 
)
inline

Non-const 6D and higher element access operator.

Parameters
i[in] first index.
j[in] second index.
k[in] third index.
m[in] fourth index.
n[in] fifth index.
p[in] sixth index.
...[in] seventh and higher indexes.

This operator should only be used with a 6D and higher MDArrays. If HAVE_DOMI_ARRAY_BOUNDSCHECK is true and the MDArray is less than 6D, an exception will be thrown.

template<typename T >
const T & Domi::MDArray< T >::operator() ( dim_type  i) const
inline

Const 1D element access operator.

Parameters
i[in] 1D index.

This operator should only be used with a 1D MDArray. If HAVE_DOMI_ARRAY_BOUNDSCHECK is true and the MDArray is not 1D, an exception will be thrown.

template<typename T >
const T & Domi::MDArray< T >::operator() ( dim_type  i,
dim_type  j 
) const
inline

Const 2D element access operator.

Parameters
i[in] first 2D index.
j[in] second 2D index.

This operator should only be used with a 2D MDArray. If HAVE_DOMI_ARRAY_BOUNDSCHECK is true and the MDArray is not 2D, an exception will be thrown.

template<typename T >
const T & Domi::MDArray< T >::operator() ( dim_type  i,
dim_type  j,
dim_type  k 
) const
inline

Const 3D element access operator.

Parameters
i[in] first 3D index.
j[in] second 3D index.
k[in] third 3D index.

This operator should only be used with a 3D MDArray. If HAVE_DOMI_ARRAY_BOUNDSCHECK is true and the MDArray is not 3D, an exception will be thrown.

template<typename T >
const T & Domi::MDArray< T >::operator() ( dim_type  i,
dim_type  j,
dim_type  k,
dim_type  m 
) const
inline

Const 4D element access operator.

Parameters
i[in] first 4D index.
j[in] second 4D index.
k[in] third 4D index.
m[in] fourth 4D index.

This operator should only be used with a 4D MDArray. If HAVE_DOMI_ARRAY_BOUNDSCHECK is true and the MDArray is not 4D, an exception will be thrown.

template<typename T >
const T & Domi::MDArray< T >::operator() ( dim_type  i,
dim_type  j,
dim_type  k,
dim_type  m,
dim_type  n 
) const
inline

Const 5D element access operator.

Parameters
i[in] first 5D index.
j[in] second 5D index.
k[in] third 5D index.
m[in] fourth 5D index.
n[in] fifth 5D index.

This operator should only be used with a 5D MDArray. If HAVE_DOMI_ARRAY_BOUNDSCHECK is true and the MDArray is not 5D, an exception will be thrown.

template<typename T >
const T & Domi::MDArray< T >::operator() ( dim_type  i,
dim_type  j,
dim_type  k,
dim_type  m,
dim_type  n,
dim_type  p,
  ... 
) const
inline

Const 6D and higher element access operator.

Parameters
i[in] first index.
j[in] second index.
k[in] third index.
m[in] fourth index.
n[in] fifth index.
p[in] sixth index.
...[in] seventh and higher indexes.

This operator should only be used with a 6D and higher MDArrays. If HAVE_DOMI_ARRAY_BOUNDSCHECK is true and the MDArray is less than 6D, an exception will be thrown.

template<typename T >
MDArrayView< T > Domi::MDArray< T >::operator[] ( dim_type  i)

Sub-array access operator. The returned MDArrayView object will have one fewer dimensions than the calling MDArray.

Parameters
i[in] Index of the desired sub-array. Note that to obtain expected behavior, you should always chain together n square bracket operators when referencing an n-dimensional MDArray.
template<typename T >
const MDArrayView< T > Domi::MDArray< T >::operator[] ( dim_type  i) const

Sub-array const access operator. The returned MDArrayView object will have one fewer dimensions than the calling MDArray.

Parameters
i[in] Index of the desired sub-array. Note that to obtain expected behavior, you should always chain together n square bracket operators when referencing an n-dimensional MDArray.
template<typename T >
MDArrayView< T > Domi::MDArray< T >::operator[] ( Slice  s)

Sub-array access operator. The returned MDArrayView object will have the same number of dimensions as the calling MDArray.

Parameters
s[in] Slice representing the bounds of the desired sub-array. Note that to obtain expected behavior, you should always chain together n square bracket operators when referencing an n-dimensional MDArray.
template<typename T >
const MDArrayView< T > Domi::MDArray< T >::operator[] ( Slice  s) const

Sub-array const access operator. The returned MDArrayView object will have the same number of dimensions as the calling MDArray.

Parameters
s[in] Slice representing the bounds of the desired sub-array. Note that to obtain expected behavior, you should always chain together n square bracket operators when referencing an n-dimensional MDArray.
template<typename T >
void Domi::MDArray< T >::resize ( const Teuchos::ArrayView< dim_type > &  dims)

Resize the MDArray based on the given dimensions.

Parameters
dims[in] New dimensions of the resized MDArray

The documentation for this class was generated from the following files:

Generated on Fri Sep 1 2023 07:56:17 for Domi by doxygen 1.8.5