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/v0.10.1/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...
AXOM_HOST_DEVICE 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 MDMapping< DIM > &	mapping () const
	Returns the multidimensional mapping for 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 >
AXOM_HOST_DEVICE	ArrayView (ArrayBase< T, DIM, OtherArrayType > &other)
	Constructor for transferring between memory spaces. More...
template<typename OtherArrayType >
AXOM_HOST_DEVICE	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 RealConstT &	flatIndex (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_SUPPRESS_HD_WARN 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 (int min_stride=1)
	Updates the internal striding information to a row-major format Intended to be called after shape is updated. 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...
MDMapping< DIM >	m_mapping
	For converting between multidim indices and offset. More...
IndexType	m_minStride
	Cached value for optimization. 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

T	the type of the values to hold.
DIM	The 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]	data	the external data this ArrayView will wrap.
[in]	args	The 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]	data	the external data this ArrayView will wrap.
[in]	shape	Array size in each dimension.
[in]	min_stride	Minimum 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]	data	the external data this ArrayView will wrap.
[in]	shape	Array size in each dimension.
[in]	strides	Array 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_HOST_DEVICE axom::ArrayView< T, DIM, SPACE >::ArrayView

(

ArrayBase< T, DIM, OtherArrayType > &

other

)

Constructor for transferring between memory spaces.

Parameters

[in]

other

The 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_HOST_DEVICE 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>

AXOM_HOST_DEVICE 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]	offset	The index where the subspan should begin.
[in]	count	The 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_SUPPRESS_HD_WARN 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]	offset	The index in each dimension where the subspan should begin.
[in]	count	The 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]

args

the 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]

idx

the 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]

args

a 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]

idx

the 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.

mapping()

AXOM_HOST_DEVICE const MDMapping<DIM>& axom::ArrayBase< T, DIM, ArrayView< T, 1, MemorySpace::Dynamic > >::mapping ( ) const

inlineinherited

Returns the multidimensional mapping for 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_SUPPRESS_HD_WARN 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 ( int  min_stride = 1 )

inlineprotectedinherited

Updates the internal striding information to a row-major format Intended to be called after shape is updated.

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_mapping

MDMapping<DIM> axom::ArrayBase< T, DIM, ArrayView< T, 1, MemorySpace::Dynamic > >::m_mapping

protectedinherited

For converting between multidim indices and offset.

m_minStride

IndexType axom::ArrayBase< T, DIM, ArrayView< T, 1, MemorySpace::Dynamic > >::m_minStride

protectedinherited

Cached value for optimization.

See also

minStride()

For some reason, computing min stride in minStride() slows down flatIndex() for CUDA and HIP, even though it doesn't seem tricky to optimize. As a work around, we cache the value in m_minStrides and update it when m_mapping changes. BTNG, March 2024.

---

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

• /home/docs/checkouts/readthedocs.org/user_builds/axom/checkouts/v0.10.1/src/axom/core/ArrayView.hpp