 |
Domi
Multi-dimensional, distributed data structures
|
|
Domi
Multi-dimensional, distributed data structures
|
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. | |
Memory-safe templated multi-dimensional array class.
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).
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
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.
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:
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:
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
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
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.
|
inline |
Default constructor.
Produces and MDArray with one dimension of length 0.
|
inline |
Constructor with dimensions only.
| 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. |
|
inline |
Constructor with dimensions and default value, with optional storage order.
| 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 |
|
inline |
Constructor with dimensions and storage order, with optional default value.
| 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 |
|
inline |
Copy constructor.
| source | [in] The source MDArray to be copied |
| Domi::MDArray< T >::MDArray | ( | const MDArrayView< T > & | source | ) |
Copy constructor from MDArrayView
| source | [in] The source MDArrayView to be copied |
| void Domi::MDArray< T >::assign | ( | const T & | value | ) |
Assign a value to all elements of the MDArray
| value | [in] The value to be assigned |
| T & Domi::MDArray< T >::at | ( | dim_type | i, |
| ... | |||
| ) |
| const T & Domi::MDArray< T >::at | ( | dim_type | i, |
| ... | |||
| ) | const |
|
inline |
Return the dimension of the given axis.
| axis | [in] The axis being queried (0 for the first axis, 1 for the second axis, and so forth) |
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
Non-const 5D element access operator.
| 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.
|
inline |
Non-const 6D and higher element access operator.
| 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.
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
Const 5D element access operator.
| 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.
|
inline |
Const 6D and higher element access operator.
| 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.
| 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.
| 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. |
| 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.
| 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. |
| 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.
| 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.
| void Domi::MDArray< T >::resize | ( | const Teuchos::ArrayView< dim_type > & | dims | ) |
1.8.5
