AXOM
Axom provides a robust, flexible software infrastructure for the development of multi-physics applications and computational tools.
axom::ArrayView< T, DIM, SPACE > Class Template Reference

Provides a view over a generic array container. More...

#include </home/docs/checkouts/readthedocs.org/user_builds/axom/checkouts/latest/src/axom/core/ArrayView.hpp>

Inheritance diagram for axom::ArrayView< T, DIM, SPACE >:

Public Types

using value_type = T
 
using ArrayViewIterator = ArrayIteratorBase< const ArrayView< T, DIM, SPACE >, T >
 
using RealConstT = typename std::conditional< is_array_view, T, const T >::type
 
using SliceType = typename std::conditional< DIM==IdxDim, T &, typename detail::SubsliceProxy< T, DIM - IdxDim, ArrayView< T, 1, MemorySpace::Dynamic > >::type >::type
 
using ConstSliceType = typename std::conditional< DIM==IdxDim, RealConstT &, typename detail::SubsliceProxy< T, DIM - IdxDim, const ArrayView< T, 1, MemorySpace::Dynamic > >::type >::type
 

Public Member Functions

AXOM_HOST_DEVICE ArrayView ()
 Default constructor. More...
 
AXOM_HOST_DEVICE IndexType size () const
 Return the number of elements stored in the data array. More...
 
AXOM_HOST_DEVICE bool empty () const
 Returns true iff the ArrayView stores no elements. More...
 
AXOM_HOST_DEVICE ArrayViewIterator begin () const
 Returns an ArrayViewIterator to the first element of the Array. More...
 
AXOM_HOST_DEVICE ArrayViewIterator end () const
 Returns an ArrayViewIterator to the element following the last element of the Array. More...
 
int getAllocatorID () const
 Get the ID for the umpire allocator. More...
 
template<int UDIM = DIM, typename Enable = typename std::enable_if<UDIM == 1>::type>
AXOM_HOST_DEVICE ArrayView subspan (IndexType offset, IndexType count=-1) const
 Returns an ArrayView that is a subspan of the original range of elements. More...
 
AXOM_HOST_DEVICE SliceType< sizeof...(Args)> operator() (Args... args)
 Dimension-aware accessor; with N=DIM indices, returns a reference to the given value at that index. Otherwise, returns a sub-array pointed to by the given sub-index. More...
 
AXOM_HOST_DEVICE ConstSliceType< sizeof...(Args)> operator() (Args... args) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...
 
AXOM_HOST_DEVICE SliceType< 1 > operator[] (const IndexType idx)
 Scalar accessor; returns a sub-array referenced by the given sub- index, beginning at array(idx, 0...) More...
 
AXOM_HOST_DEVICE ConstSliceType< 1 > operator[] (const IndexType idx) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...
 
AXOM_HOST_DEVICE SliceType< UDim > operator[] (const StackArray< IndexType, UDim > &idx)
 Dimension-aware accessor; with UDim=DIM indices, returns a reference to the given value at that index. Otherwise, returns a sub-array pointed to by the given sub-index. More...
 
AXOM_HOST_DEVICE ConstSliceType< UDim > operator[] (const StackArray< IndexType, UDim > &idx) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...
 
void swap (ArrayBase &other)
 Swaps two ArrayBases. More...
 
AXOM_HOST_DEVICE const StackArray< IndexType, DIM > & shape () const
 Returns the dimensions of the Array. More...
 
AXOM_HOST_DEVICE const StackArray< IndexType, DIM > & strides () const
 Returns the memory strides of the Array. More...
 
AXOM_HOST_DEVICE IndexType minStride () const
 Returns the minimum stride between adjacent items. More...
 
ArrayView to wrap a pointer and provide indexing semantics
template<typename... Args, typename Enable = typename std::enable_if< sizeof...(Args) == DIM && detail::all_types_are_integral<Args...>::value>::type>
 ArrayView (T *data, Args... args)
 Generic constructor for an ArrayView of arbitrary dimension with external data. More...
 
AXOM_HOST_DEVICE ArrayView (T *data, const StackArray< IndexType, DIM > &shape, IndexType min_stride=1)
 Generic constructor for an ArrayView of arbitrary dimension with external data. More...
 
AXOM_HOST_DEVICE ArrayView (T *data, const StackArray< IndexType, DIM > &shape, const StackArray< IndexType, DIM > &stride)
 Generic constructor for an ArrayView of arbitrary dimension with external data. More...
 
template<typename OtherArrayType >
 ArrayView (ArrayBase< T, DIM, OtherArrayType > &other)
 Constructor for transferring between memory spaces. More...
 
template<typename OtherArrayType >
 ArrayView (const ArrayBase< typename std::remove_const< T >::type, DIM, OtherArrayType > &other)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...
 
AXOM_HOST_DEVICE ArrayView subspan (const StackArray< IndexType, DIM > &offsets, const StackArray< IndexType, DIM > &counts)
 Returns an ArrayView that is a subspan of the original range of elements. More...
 
AXOM_HOST_DEVICE T * data () const
 Return a pointer to the array of data. More...
 
AXOM_HOST_DEVICE T & flatIndex (const IndexType idx)
 Accessor, returns a reference to the given value. For multidimensional arrays, indexes into the (flat) raw data. More...
 
AXOM_HOST_DEVICE RealConstTflatIndex (const IndexType idx) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...
 

Static Public Attributes

static constexpr int dimension = DIM
 
static constexpr MemorySpace space = SPACE
 
constexpr static int Dims
 

Protected Member Functions

AXOM_HOST_DEVICE void setShape (const StackArray< IndexType, DIM > &shape_)
 Set the shape. More...
 
AXOM_HOST_DEVICE void setShapeAndStride (const StackArray< IndexType, DIM > &shape, const StackArray< IndexType, DIM > &stride)
 Set the shape and stride. More...
 
IndexType blockSize () const
 Returns the minimum "chunk size" that should be allocated For example, 2 would be the chunk size of a 2D array whose second dimension is of size 2. This is used when resizing/reallocating; it wouldn't make sense to have a capacity of 3 in the array described above. More...
 
AXOM_HOST_DEVICE void updateStrides ()
 Updates the internal striding information to a row-major format Intended to be called after shape is updated. In the future, this class will support different striding schemes (e.g., column-major) and/or user-provided striding. More...
 
void updateShapeOnInsert (const StackArray< IndexType, DIM > &range_shape)
 Updates the internal dimensions and striding based on the insertion of a range of elements. Intended to be called after the insertion of a multidimensional subslice. More...
 

Protected Attributes

StackArray< IndexType, DIM > m_shape
 The extent in each direction. More...
 
StackArray< IndexType, DIM > m_strides
 Logical strides in each direction. More...
 

Detailed Description

template<typename T, int DIM = 1, MemorySpace SPACE = MemorySpace::Dynamic>
class axom::ArrayView< T, DIM, SPACE >

Provides a view over a generic array container.

The ArrayView expresses a non-owning relationship over a pointer

Template Parameters
Tthe type of the values to hold.
DIMThe dimension of the array.

Member Typedef Documentation

◆ value_type

template<typename T , int DIM = 1, MemorySpace SPACE = MemorySpace::Dynamic>
using axom::ArrayView< T, DIM, SPACE >::value_type = T

◆ ArrayViewIterator

template<typename T , int DIM = 1, MemorySpace SPACE = MemorySpace::Dynamic>
using axom::ArrayView< T, DIM, SPACE >::ArrayViewIterator = ArrayIteratorBase<const ArrayView<T, DIM, SPACE>, T>

◆ RealConstT

using axom::ArrayBase< T, DIM, ArrayView< T, 1, MemorySpace::Dynamic > >::RealConstT = typename std::conditional<is_array_view, T, const T>::type
inherited

◆ SliceType

using axom::ArrayBase< T, DIM, ArrayView< T, 1, MemorySpace::Dynamic > >::SliceType = typename std::conditional< DIM == IdxDim, T&, typename detail::SubsliceProxy<T, DIM - IdxDim, ArrayView< T, 1, MemorySpace::Dynamic > >::type>::type
inherited

◆ ConstSliceType

using axom::ArrayBase< T, DIM, ArrayView< T, 1, MemorySpace::Dynamic > >::ConstSliceType = typename std::conditional< DIM == IdxDim, RealConstT&, typename detail::SubsliceProxy<T, DIM - IdxDim, const ArrayView< T, 1, MemorySpace::Dynamic > >::type>::type
inherited

Constructor & Destructor Documentation

◆ ArrayView() [1/6]

template<typename T , int DIM = 1, MemorySpace SPACE = MemorySpace::Dynamic>
AXOM_HOST_DEVICE axom::ArrayView< T, DIM, SPACE >::ArrayView ( )
inline

Default constructor.

◆ ArrayView() [2/6]

template<typename T , int DIM, MemorySpace SPACE>
template<typename... Args, typename Enable >
axom::ArrayView< T, DIM, SPACE >::ArrayView ( T *  data,
Args...  args 
)

Generic constructor for an ArrayView of arbitrary dimension with external data.

This constructor assumes that the data is laid out in a dense row-major layout; that is, elements are laid out contiguously with respect to the last (DIM-1) dimension.

Parameters
[in]datathe external data this ArrayView will wrap.
[in]argsThe parameter pack containing the "shape" of the ArrayView
Precondition
sizeof...(Args) == DIM

◆ ArrayView() [3/6]

template<typename T , int DIM, MemorySpace SPACE>
AXOM_HOST_DEVICE axom::ArrayView< T, DIM, SPACE >::ArrayView ( T *  data,
const StackArray< IndexType, DIM > &  shape,
IndexType  min_stride = 1 
)

Generic constructor for an ArrayView of arbitrary dimension with external data.

This constructor assumes that the data is laid out in a row-major layout, but accepts a min_stride parameter for the stride between consecutive elements in the last dimension.

Parameters
[in]datathe external data this ArrayView will wrap.
[in]shapeArray size in each dimension.
[in]min_strideMinimum stride between consecutive items in the last dimension

References axom::ArrayView< T, DIM, SPACE >::data(), axom::Dynamic, axom::StackArray< T, N >::m_data, axom::detail::packProduct(), and axom::ArrayBase< T, 1, ArrayView< T, 1, MemorySpace::Dynamic > >::shape().

◆ ArrayView() [4/6]

template<typename T , int DIM, MemorySpace SPACE>
AXOM_HOST_DEVICE axom::ArrayView< T, DIM, SPACE >::ArrayView ( T *  data,
const StackArray< IndexType, DIM > &  shape,
const StackArray< IndexType, DIM > &  stride 
)

Generic constructor for an ArrayView of arbitrary dimension with external data.

Parameters
[in]datathe external data this ArrayView will wrap.
[in]shapeArray size in each dimension.
[in]stridesArray strides for each dimension.

References axom::ArrayView< T, DIM, SPACE >::data(), axom::Dynamic, axom::StackArray< T, N >::m_data, axom::detail::packProduct(), and axom::ArrayBase< T, 1, ArrayView< T, 1, MemorySpace::Dynamic > >::shape().

◆ ArrayView() [5/6]

template<typename T , int DIM, MemorySpace SPACE>
template<typename OtherArrayType >
axom::ArrayView< T, DIM, SPACE >::ArrayView ( ArrayBase< T, DIM, OtherArrayType > &  other)

Constructor for transferring between memory spaces.

Parameters
[in]otherThe array in a different memory space to copy from
Note
The parameter is non-const because other can be modified through the constructed View
This constructor is left implicit to allow for convenient function calls that convert from Array -> ArrayView or from dynamic memory spaces to an ArrayView of explicitly specified space.

References axom::Dynamic, axom::detail::getAllocatorSpace(), and axom::utilities::processAbort().

◆ ArrayView() [6/6]

template<typename T , int DIM, MemorySpace SPACE>
template<typename OtherArrayType >
axom::ArrayView< T, DIM, SPACE >::ArrayView ( const ArrayBase< typename std::remove_const< T >::type, DIM, OtherArrayType > &  other)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

References axom::Dynamic, axom::detail::getAllocatorSpace(), and axom::utilities::processAbort().

Member Function Documentation

◆ size()

template<typename T , int DIM = 1, MemorySpace SPACE = MemorySpace::Dynamic>
AXOM_HOST_DEVICE IndexType axom::ArrayView< T, DIM, SPACE >::size ( ) const
inline

Return the number of elements stored in the data array.

◆ empty()

template<typename T , int DIM = 1, MemorySpace SPACE = MemorySpace::Dynamic>
AXOM_HOST_DEVICE bool axom::ArrayView< T, DIM, SPACE >::empty ( ) const
inline

Returns true iff the ArrayView stores no elements.

◆ begin()

template<typename T , int DIM = 1, MemorySpace SPACE = MemorySpace::Dynamic>
AXOM_HOST_DEVICE ArrayViewIterator axom::ArrayView< T, DIM, SPACE >::begin ( ) const
inline

Returns an ArrayViewIterator to the first element of the Array.

◆ end()

template<typename T , int DIM = 1, MemorySpace SPACE = MemorySpace::Dynamic>
AXOM_HOST_DEVICE ArrayViewIterator axom::ArrayView< T, DIM, SPACE >::end ( ) const
inline

Returns an ArrayViewIterator to the element following the last element of the Array.

References axom::ArrayView< T, DIM, SPACE >::size().

◆ data()

template<typename T , int DIM = 1, MemorySpace SPACE = MemorySpace::Dynamic>
AXOM_HOST_DEVICE T* axom::ArrayView< T, DIM, SPACE >::data ( ) const
inline

Return a pointer to the array of data.

◆ getAllocatorID()

template<typename T , int DIM = 1, MemorySpace SPACE = MemorySpace::Dynamic>
int axom::ArrayView< T, DIM, SPACE >::getAllocatorID ( ) const
inline

Get the ID for the umpire allocator.

◆ subspan() [1/2]

template<typename T , int DIM = 1, MemorySpace SPACE = MemorySpace::Dynamic>
template<int UDIM = DIM, typename Enable = typename std::enable_if<UDIM == 1>::type>
AXOM_HOST_DEVICE ArrayView axom::ArrayView< T, DIM, SPACE >::subspan ( IndexType  offset,
IndexType  count = -1 
) const
inline

Returns an ArrayView that is a subspan of the original range of elements.

Parameters
[in]offsetThe index where the subspan should begin.
[in]countThe number of elements to include in the subspan, or -1 to take all elements after offset (default).
Returns
An ArrayView that spans the indices [offset, offset + count), or [offset, num_elements) if count < 0.
Precondition
offset + count <= m_num_elements if count < 0

◆ subspan() [2/2]

template<typename T , int DIM, MemorySpace SPACE>
AXOM_HOST_DEVICE ArrayView< T, DIM, SPACE > axom::ArrayView< T, DIM, SPACE >::subspan ( const StackArray< IndexType, DIM > &  offsets,
const StackArray< IndexType, DIM > &  counts 
)

Returns an ArrayView that is a subspan of the original range of elements.

Parameters
[in]offsetThe index in each dimension where the subspan should begin.
[in]countThe number of elements in each dimension to include in the subspan. -1 in any dimension indicates to take all elements after the offset for that domain.
Returns
An ArrayView that spans in each dimension the indices:
  • [offsets[i], offsets[i] + counts[i])
  • or [offsets[i], shape[i]) if count < 0.
Precondition
offsets[i] + counts[i] < shape[i] for 0 <= i < DIM

References axom::numerics::dot_product(), axom::StackArray< T, N >::m_data, axom::detail::packProduct(), and axom::ArrayBase< T, DIM, ArrayType >::setShapeAndStride().

◆ operator()() [1/2]

AXOM_HOST_DEVICE SliceType<sizeof...(Args)> axom::ArrayBase< T, DIM, ArrayView< T, 1, MemorySpace::Dynamic > >::operator() ( Args...  args)
inlineinherited

Dimension-aware accessor; with N=DIM indices, returns a reference to the given value at that index. Otherwise, returns a sub-array pointed to by the given sub-index.

Parameters
[in]argsthe parameter pack of indices in each dimension.
Note
equivalent to *(array.data() + idx).
Precondition
sizeof...(Args) <= DIM
0 <= args[i] < shape()[i] for i in [0, sizeof...(Args))

◆ operator()() [2/2]

AXOM_HOST_DEVICE ConstSliceType<sizeof...(Args)> axom::ArrayBase< T, DIM, ArrayView< T, 1, MemorySpace::Dynamic > >::operator() ( Args...  args) const
inlineinherited

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ operator[]() [1/4]

AXOM_HOST_DEVICE SliceType<1> axom::ArrayBase< T, DIM, ArrayView< T, 1, MemorySpace::Dynamic > >::operator[] ( const IndexType  idx)
inlineinherited

Scalar accessor; returns a sub-array referenced by the given sub- index, beginning at array(idx, 0...)

Parameters
[in]idxthe index of the first dimension.
Precondition
0 <= idx < shape()[0]

◆ operator[]() [2/4]

AXOM_HOST_DEVICE ConstSliceType<1> axom::ArrayBase< T, DIM, ArrayView< T, 1, MemorySpace::Dynamic > >::operator[] ( const IndexType  idx) const
inlineinherited

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ operator[]() [3/4]

AXOM_HOST_DEVICE SliceType<UDim> axom::ArrayBase< T, DIM, ArrayView< T, 1, MemorySpace::Dynamic > >::operator[] ( const StackArray< IndexType, UDim > &  idx)
inlineinherited

Dimension-aware accessor; with UDim=DIM indices, returns a reference to the given value at that index. Otherwise, returns a sub-array pointed to by the given sub-index.

Parameters
[in]argsa stack array of indices in each dimension.
Note
equivalent to *(array.data() + idx).
Precondition
UDim <= DIM
0 <= args[i] < shape()[i] for i in [0, UDim)

◆ operator[]() [4/4]

AXOM_HOST_DEVICE ConstSliceType<UDim> axom::ArrayBase< T, DIM, ArrayView< T, 1, MemorySpace::Dynamic > >::operator[] ( const StackArray< IndexType, UDim > &  idx) const
inlineinherited

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ flatIndex() [1/2]

AXOM_HOST_DEVICE T& axom::ArrayBase< T, DIM, ArrayView< T, 1, MemorySpace::Dynamic > >::flatIndex ( const IndexType  idx)
inlineinherited

Accessor, returns a reference to the given value. For multidimensional arrays, indexes into the (flat) raw data.

Parameters
[in]idxthe position of the value to return.
Note
equivalent to *(array.data() + idx * minStride()).
Precondition
0 <= idx < asDerived().size()

◆ flatIndex() [2/2]

AXOM_HOST_DEVICE RealConstT& axom::ArrayBase< T, DIM, ArrayView< T, 1, MemorySpace::Dynamic > >::flatIndex ( const IndexType  idx) const
inlineinherited

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ swap()

void axom::ArrayBase< T, DIM, ArrayView< T, 1, MemorySpace::Dynamic > >::swap ( ArrayBase< T, 1, ArrayView< T, 1, MemorySpace::Dynamic > > &  other)
inlineinherited

Swaps two ArrayBases.

◆ shape()

AXOM_HOST_DEVICE const StackArray<IndexType, DIM>& axom::ArrayBase< T, DIM, ArrayView< T, 1, MemorySpace::Dynamic > >::shape ( ) const
inlineinherited

Returns the dimensions of the Array.

◆ strides()

AXOM_HOST_DEVICE const StackArray<IndexType, DIM>& axom::ArrayBase< T, DIM, ArrayView< T, 1, MemorySpace::Dynamic > >::strides ( ) const
inlineinherited

Returns the memory strides of the Array.

◆ minStride()

AXOM_HOST_DEVICE IndexType axom::ArrayBase< T, DIM, ArrayView< T, 1, MemorySpace::Dynamic > >::minStride ( ) const
inlineinherited

Returns the minimum stride between adjacent items.

◆ setShape()

AXOM_HOST_DEVICE void axom::ArrayBase< T, DIM, ArrayView< T, 1, MemorySpace::Dynamic > >::setShape ( const StackArray< IndexType, DIM > &  shape_)
inlineprotectedinherited

Set the shape.

◆ setShapeAndStride()

AXOM_HOST_DEVICE void axom::ArrayBase< T, DIM, ArrayView< T, 1, MemorySpace::Dynamic > >::setShapeAndStride ( const StackArray< IndexType, DIM > &  shape,
const StackArray< IndexType, DIM > &  stride 
)
inlineprotectedinherited

Set the shape and stride.

◆ blockSize()

IndexType axom::ArrayBase< T, DIM, ArrayView< T, 1, MemorySpace::Dynamic > >::blockSize ( ) const
inlineprotectedinherited

Returns the minimum "chunk size" that should be allocated For example, 2 would be the chunk size of a 2D array whose second dimension is of size 2. This is used when resizing/reallocating; it wouldn't make sense to have a capacity of 3 in the array described above.

◆ updateStrides()

AXOM_HOST_DEVICE void axom::ArrayBase< T, DIM, ArrayView< T, 1, MemorySpace::Dynamic > >::updateStrides ( )
inlineprotectedinherited

Updates the internal striding information to a row-major format Intended to be called after shape is updated. In the future, this class will support different striding schemes (e.g., column-major) and/or user-provided striding.

◆ updateShapeOnInsert()

void axom::ArrayBase< T, DIM, ArrayView< T, 1, MemorySpace::Dynamic > >::updateShapeOnInsert ( const StackArray< IndexType, DIM > &  range_shape)
inlineprotectedinherited

Updates the internal dimensions and striding based on the insertion of a range of elements. Intended to be called after the insertion of a multidimensional subslice.

Member Data Documentation

◆ dimension

template<typename T , int DIM = 1, MemorySpace SPACE = MemorySpace::Dynamic>
constexpr int axom::ArrayView< T, DIM, SPACE >::dimension = DIM
staticconstexpr

◆ space

template<typename T , int DIM = 1, MemorySpace SPACE = MemorySpace::Dynamic>
constexpr MemorySpace axom::ArrayView< T, DIM, SPACE >::space = SPACE
staticconstexpr

◆ Dims

constexpr static int axom::ArrayBase< T, DIM, ArrayView< T, 1, MemorySpace::Dynamic > >::Dims
staticconstexprinherited

◆ m_shape

StackArray<IndexType, DIM> axom::ArrayBase< T, DIM, ArrayView< T, 1, MemorySpace::Dynamic > >::m_shape
protectedinherited

The extent in each direction.

◆ m_strides

StackArray<IndexType, DIM> axom::ArrayBase< T, DIM, ArrayView< T, 1, MemorySpace::Dynamic > >::m_strides
protectedinherited

Logical strides in each direction.


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