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

Provides a generic multi-component array, constructed from external storage. More...

#include </home/docs/checkouts/readthedocs.org/user_builds/axom/checkouts/develop/src/axom/mint/utils/ExternalArray.hpp>

Inheritance diagram for axom::mint::ExternalArray< T, DIM >:

Public Types

using BaseClass = axom::Array< T, DIM >
 
using value_type = T
 
using ArrayIterator = ArrayIteratorBase< Array< T, DIM, MemorySpace::Dynamic >, T >
 
using ConstArrayIterator = ArrayIteratorBase< const Array< T, DIM, MemorySpace::Dynamic >, const T >
 
using ArrayViewType = ArrayView< T, DIM, MemorySpace::Dynamic >
 
using ConstArrayViewType = ArrayView< const T, DIM, MemorySpace::Dynamic >
 
using RealConstT = typename std::conditional< is_array_view, T, const T >::type
 
template<int IdxDim>
using SliceType = typename std::conditional< DIM==IdxDim, T &, typename detail::SubsliceProxy< T, DIM - IdxDim, ArrayType >::type >::type
 
template<int IdxDim>
using ConstSliceType = typename std::conditional< DIM==IdxDim, RealConstT &, typename detail::SubsliceProxy< T, DIM - IdxDim, const ArrayType >::type >::type
 

Public Member Functions

 ExternalArray ()=delete
 Default constructor. Disabled. More...
 
 ExternalArray (ExternalArray &&other)
 Move constructor. More...
 
virtual ~ExternalArray ()
 
ExternalArrayoperator= (ExternalArray &&other)
 Move assignment. More...
 
std::enable_if< TDIM==1, axom::StackArray< TT, LENGTH1D > >::type to_stack_array () const
 Convert 1D Array into a StackArray. More...
 
Array< T, DIM, MemorySpace::Dynamic >::ArrayIterator emplace (Array< T, DIM, MemorySpace::Dynamic >::ArrayIterator pos, Args &&... args)
 
void swap (ArrayBase &other)
 Swaps two ArrayBases. More...
 
template<typename... Args>
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...
 
template<typename... Args>
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...
 
template<int UDim>
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...
 
template<int UDim>
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...
 
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...
 
ExternalArray constructors
template<int UDIM = DIM, typename Enable = std::enable_if_t<UDIM != 1>>
 ExternalArray (T *data, const StackArray< IndexType, DIM > &shape, IndexType capacity)
 Generic constructor for an ExternalArray of arbitrary dimension. More...
 
template<int UDIM = DIM, typename Enable = std::enable_if_t<UDIM == 1>>
 ExternalArray (T *data, IndexType size, IndexType capacity)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...
 
Array element access operators
T * data ()
 Return a pointer to the array of data. More...
 
const T * data () const
 
Array methods to modify the data.
void fill (const T &value)
 Set all the values of the array. More...
 
void fill (const T &value, IndexType n, IndexType pos)
 Set a range of elements to a given value. More...
 
void set (const T *elements, IndexType n, IndexType pos)
 Modify the values of existing elements. More...
 
void clear ()
 Clears the contents of the array. More...
 
void insert (IndexType pos, const T &value)
 Insert an element into the array at the given position. More...
 
ArrayIterator insert (ArrayIterator pos, const T &value)
 Insert an element into the array at the value before pos. More...
 
void insert (IndexType pos, IndexType n, const T *values)
 Insert elements into the array at the given position. More...
 
ArrayIterator insert (ArrayIterator pos, IndexType n, const T *values)
 Insert elements into the array at the value before pos. More...
 
void insert (IndexType pos, IndexType n, const T &value)
 Insert n copies of element into the array at the given position. More...
 
ArrayIterator insert (ArrayIterator pos, IndexType n, const T &value)
 Insert n copies of element into the array at the value before pos. More...
 
void insert (IndexType pos, ArrayView< const T, DIM, OtherSpace > other)
 Inserts an Array to the end of the calling object. More...
 
void insert (IndexType pos, ArrayView< T, DIM, OtherSpace > other)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...
 
void append (ArrayView< const T, DIM, OtherSpace > other)
 Appends an Array to the end of the calling object. More...
 
void append (ArrayView< T, DIM, OtherSpace > other)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...
 
ArrayIterator erase (ArrayIterator pos)
 Erases an element from the Array. More...
 
ArrayIterator erase (ArrayIterator first, ArrayIterator last)
 Erases elements in the range [first, last) from the Array. More...
 
void emplace (IndexType pos, Args &&... args)
 Inserts new element into Array at the given position. More...
 
ArrayIterator emplace (ArrayIterator pos, Args &&... args)
 Inserts new element into Array before pos. More...
 
void push_back (const T &value)
 Push a value to the back of the array. More...
 
void push_back (T &&value)
 Push a value to the back of the array. More...
 
void emplace_back (Args &&... args)
 Inserts new element at the end of the Array. More...
 
Array methods to query and set attributes
IndexType capacity () const
 Return the number of elements allocated for the data array. More...
 
void reserve (IndexType capacity)
 Increase the capacity. Does nothing if the new capacity is less than the current capacity. More...
 
ArrayIterator begin ()
 Returns an ArrayIterator to the first element of the Array. More...
 
ConstArrayIterator begin () const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...
 
ArrayIterator end ()
 Returns an ArrayIterator to the element following the last element of the Array. More...
 
ConstArrayIterator end () const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...
 
T & front ()
 Returns a reference to the first element in the Array. More...
 
const T & front () const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...
 
T & back ()
 Returns a reference to the last element in the Array. More...
 
const T & back () 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 shrink ()
 Shrink the capacity to be equal to the size. More...
 
bool empty () const
 Returns true iff the Array stores no elements. More...
 
IndexType size () const
 Return the number of elements stored in the data array. More...
 
void resize (Args... args)
 Update the number of elements stored in the data array. More...
 
void resize (ArrayOptions::Uninitialized, Args... args)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...
 
void resize (IndexType size, const T &value)
 
void resize (const StackArray< IndexType, DIM > &size, const T &value)
 
void swap (Array< T, DIM, MemorySpace::Dynamic > &other)
 Exchanges the contents of this Array with the other. More...
 
double getResizeRatio () const
 Get the ratio by which the capacity increases upon dynamic resize. More...
 
void setResizeRatio (double ratio)
 Set the ratio by which the capacity increases upon dynamic resize. More...
 
int getAllocatorID () const
 Get the ID for the umpire allocator. More...
 
ArrayViewType view ()
 Returns a view of the array. More...
 
ConstArrayViewType view () 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 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 double DEFAULT_RESIZE_RATIO
 
static constexpr IndexType MIN_DEFAULT_CAPACITY
 
static constexpr MemorySpace space
 
constexpr static int Dims = DIM
 

Protected Member Functions

virtual void setCapacity (axom::IndexType new_capacity)
 Set the number of elements allocated for the data array. More...
 
virtual void dynamicRealloc (axom::IndexType new_num_elements)
 Reallocates the data array when the size exceeds the capacity. More...
 
void initialize (IndexType num_elements, IndexType capacity, bool should_default_construct=true)
 Initialize an Array instance with the given number of elements. More...
 
void initialize_from_other (const T *data, IndexType num_elements, MemorySpace data_space, bool user_provided_allocator)
 Helper function for initializing an Array instance with an existing range of elements. More...
 
void resizeImpl (const StackArray< IndexType, DIM > &dims, bool construct_with_values, const T *value=nullptr)
 Updates the number of elements stored in the data array. More...
 
T * reserveForInsert (IndexType n, IndexType pos)
 Make space for a subsequent insertion into the array. More...
 
IndexType reserveForDeviceInsert (IndexType n)
 Make space for a subsequent insertion into the array. More...
 
virtual void updateNumElements (IndexType new_num_elements)
 Update the number of elements. More...
 
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

T * m_data
 
IndexType m_num_elements
 The full number of elements in the array i.e., 3 for a 1D Array of size 3, 9 for a 3x3 2D array, etc. More...
 
IndexType m_capacity
 
double m_resize_ratio
 
int m_allocator_id
 
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>
class axom::mint::ExternalArray< T, DIM >

Provides a generic multi-component array, constructed from external storage.

This ExternalArray class extends axom::Array by storing data in an externally-owned buffer. This class provides a generic multi-component array container with dynamic resizing and insertion. Each element in the array is a tuple consisting of 1 or more components, which are stored contiguously.

All array operations can be performed as with the base axom::Array class, with the exception of operations that require reallocation of the underlying buffer.

Note
When the Array object is deleted, it does not delete the associated data.
Template Parameters
Tthe type of the values to hold.

Member Typedef Documentation

◆ BaseClass

template<typename T , int DIM = 1>
using axom::mint::ExternalArray< T, DIM >::BaseClass = axom::Array<T, DIM>

◆ value_type

using axom::Array< T, DIM, MemorySpace::Dynamic >::value_type = T
inherited

◆ ArrayIterator

◆ ConstArrayIterator

using axom::Array< T, DIM, MemorySpace::Dynamic >::ConstArrayIterator = ArrayIteratorBase<const Array<T, DIM, MemorySpace::Dynamic >, const T>
inherited

◆ ArrayViewType

◆ ConstArrayViewType

using axom::Array< T, DIM, MemorySpace::Dynamic >::ConstArrayViewType = ArrayView<const T, DIM, MemorySpace::Dynamic >
inherited

◆ RealConstT

template<typename T , int DIM, typename ArrayType >
using axom::ArrayBase< T, DIM, ArrayType >::RealConstT = typename std::conditional<is_array_view, T, const T>::type
inherited

◆ SliceType

template<typename T , int DIM, typename ArrayType >
template<int IdxDim>
using axom::ArrayBase< T, DIM, ArrayType >::SliceType = typename std::conditional< DIM == IdxDim, T&, typename detail::SubsliceProxy<T, DIM - IdxDim, ArrayType>::type>::type
inherited

◆ ConstSliceType

template<typename T , int DIM, typename ArrayType >
template<int IdxDim>
using axom::ArrayBase< T, DIM, ArrayType >::ConstSliceType = typename std::conditional< DIM == IdxDim, RealConstT&, typename detail::SubsliceProxy<T, DIM - IdxDim, const ArrayType>::type>::type
inherited

Constructor & Destructor Documentation

◆ ExternalArray() [1/4]

template<typename T , int DIM = 1>
axom::mint::ExternalArray< T, DIM >::ExternalArray ( )
delete

Default constructor. Disabled.

◆ ExternalArray() [2/4]

template<typename T , int DIM = 1>
axom::mint::ExternalArray< T, DIM >::ExternalArray ( ExternalArray< T, DIM > &&  other)
inline

Move constructor.

Parameters
[in]otherThe array to move from

◆ ExternalArray() [3/4]

template<typename T , int DIM = 1>
template<int UDIM = DIM, typename Enable = std::enable_if_t<UDIM != 1>>
axom::mint::ExternalArray< T, DIM >::ExternalArray ( T *  data,
const StackArray< IndexType, DIM > &  shape,
IndexType  capacity 
)
inline

◆ ExternalArray() [4/4]

template<typename T , int DIM = 1>
template<int UDIM = DIM, typename Enable = std::enable_if_t<UDIM == 1>>
axom::mint::ExternalArray< T, DIM >::ExternalArray ( T *  data,
IndexType  size,
IndexType  capacity 
)
inline

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

References axom::Array< T, 1 >::capacity(), axom::Array< T, 1 >::data(), axom::Array< T, 1 >::m_capacity, axom::Array< T, 1 >::m_data, axom::Array< T, 1 >::m_num_elements, axom::Array< T, 1 >::size(), SLIC_ASSERT, and SLIC_WARNING.

◆ ~ExternalArray()

template<typename T , int DIM = 1>
virtual axom::mint::ExternalArray< T, DIM >::~ExternalArray ( )
inlinevirtual

Member Function Documentation

◆ operator=()

template<typename T , int DIM = 1>
ExternalArray& axom::mint::ExternalArray< T, DIM >::operator= ( ExternalArray< T, DIM > &&  other)
inline

Move assignment.

Parameters
[in]otherThe ExternalArray to move from

References axom::Array< T, DIM, SPACE >::operator=().

◆ setCapacity()

template<typename T , int DIM = 1>
virtual void axom::mint::ExternalArray< T, DIM >::setCapacity ( axom::IndexType  new_capacity)
inlineprotectedvirtual

Set the number of elements allocated for the data array.

Parameters
[in]capacitythe new number of elements to allocate.

Reimplemented from axom::Array< T, 1 >.

References axom::Array< T, 1 >::m_capacity, and SLIC_ERROR.

◆ dynamicRealloc()

template<typename T , int DIM = 1>
virtual void axom::mint::ExternalArray< T, DIM >::dynamicRealloc ( axom::IndexType  new_num_elements)
inlineprotectedvirtual

Reallocates the data array when the size exceeds the capacity.

Parameters
[in]new_num_elementsthe number of elements which exceeds the current capacity.

Reimplemented from axom::Array< T, 1 >.

References AXOM_UNUSED_VAR, and SLIC_ERROR.

◆ data() [1/2]

T* axom::Array< T, DIM, MemorySpace::Dynamic >::data ( )
inlineinherited

Return a pointer to the array of data.

◆ data() [2/2]

const T* axom::Array< T, DIM, MemorySpace::Dynamic >::data ( ) const
inlineinherited

◆ to_stack_array()

std::enable_if<TDIM == 1, axom::StackArray<TT, LENGTH1D> >::type axom::Array< T, DIM, MemorySpace::Dynamic >::to_stack_array ( ) const
inlineinherited

Convert 1D Array into a StackArray.

◆ fill() [1/2]

void axom::Array< T, DIM, MemorySpace::Dynamic >::fill ( const T &  value)
inlineinherited

Set all the values of the array.

Parameters
[in]valuethe value to set to.

◆ fill() [2/2]

void axom::Array< T, DIM, MemorySpace::Dynamic >::fill ( const T &  value,
IndexType  n,
IndexType  pos 
)
inlineinherited

Set a range of elements to a given value.

Parameters
[in]valuethe value to set to.
[in]nthe number of elements to write.
[in]posthe position at which to begin writing.
Note
The size is unchanged by calls to fill.
Precondition
pos + n <= m_num_elements.

◆ set()

void axom::Array< T, DIM, MemorySpace::Dynamic >::set ( const T *  elements,
IndexType  n,
IndexType  pos 
)
inlineinherited

Modify the values of existing elements.

Parameters
[in]elementsthe new elements to write.
[in]nthe number of elements to write.
[in]posthe position at which to begin writing.
Note
It's assumed that elements is of length n.
The size is unchanged by calls to set.
Precondition
pos + n <= m_num_elements.

◆ clear()

void axom::Array< T, DIM, MemorySpace::Dynamic >::clear
inlineinherited

Clears the contents of the array.

Postcondition
size of Array is 0
capacity is unchanged

◆ insert() [1/8]

void axom::Array< T, DIM, MemorySpace::Dynamic >::insert ( IndexType  pos,
const T &  value 
)
inlineinherited

Insert an element into the array at the given position.

Parameters
[in]posthe position at which to insert.
[in]valuethe element value to insert.
Note
Reallocation is done if the new size will exceed the capacity.
The size increases by 1.

◆ insert() [2/8]

ArrayIterator axom::Array< T, DIM, MemorySpace::Dynamic >::insert ( ArrayIterator  pos,
const T &  value 
)
inherited

Insert an element into the array at the value before pos.

Parameters
[in]posthe ArrayIterator before which value will be inserted.
[in]valuethe element value to insert.
Note
Reallocation is done if the new size will exceed the capacity.
The size increases by 1.
Returns
ArrayIterator to inserted value

◆ insert() [3/8]

void axom::Array< T, DIM, MemorySpace::Dynamic >::insert ( IndexType  pos,
IndexType  n,
const T *  values 
)
inlineinherited

Insert elements into the array at the given position.

Parameters
[in]posthe position at which to begin the insertion.
[in]nthe number of elements to insert.
[in]valuesthe element values to insert.
Note
It's assumed that elements is of length n.
Reallocation is done if the new size will exceed the capacity.
The size increases by n.
Precondition
pos <= m_num_elements.

◆ insert() [4/8]

ArrayIterator axom::Array< T, DIM, MemorySpace::Dynamic >::insert ( ArrayIterator  pos,
IndexType  n,
const T *  values 
)
inherited

Insert elements into the array at the value before pos.

Parameters
[in]posthe ArrayIterator before which value will be inserted.
[in]nthe number of elements to insert.
[in]valuesthe element values to insert.
Note
It's assumed that elements is of length n.
Reallocation is done if the new size will exceed the capacity.
The size increases by n.
Precondition
pos <= end()
Returns
ArrayIterator to first element inserted (pos if n == 0)

◆ insert() [5/8]

void axom::Array< T, DIM, MemorySpace::Dynamic >::insert ( IndexType  pos,
IndexType  n,
const T &  value 
)
inlineinherited

Insert n copies of element into the array at the given position.

Parameters
[in]posthe position at which to begin the insertion.
[in]nthe number of elements to insert.
[in]valuethe element value to insert.
Note
Reallocation is done if the new size will exceed the capacity.
The size increases by n.
This method is used to create space for elements in the middle of the array.
Precondition
pos <= m_num_elements.

◆ insert() [6/8]

ArrayIterator axom::Array< T, DIM, MemorySpace::Dynamic >::insert ( ArrayIterator  pos,
IndexType  n,
const T &  value 
)
inherited

Insert n copies of element into the array at the value before pos.

Parameters
[in]posthe ArrayIterator before which value will be inserted.
[in]nthe number of elements to insert.
[in]valuethe element value to insert.
Note
Reallocation is done if the new size will exceed the capacity.
The size increases by n.
This method is used to create space for elements in the middle of the array.
Precondition
pos <= end()
Returns
ArrayIterator to first element inserted (pos if n == 0)

◆ insert() [7/8]

void axom::Array< T, DIM, MemorySpace::Dynamic >::insert ( IndexType  pos,
ArrayView< const T, DIM, OtherSpace >  other 
)
inlineinherited

Inserts an Array to the end of the calling object.

Parameters
[in]otherThe Array to append
Precondition
The shapes of the calling Array and other are the same (excluding the leading dimension), i.e., shape()[1:] == other.shape()[1:]
Note
Reallocation is done if the new size will exceed the capacity.

◆ insert() [8/8]

void axom::Array< T, DIM, MemorySpace::Dynamic >::insert ( IndexType  pos,
ArrayView< T, DIM, OtherSpace >  other 
)
inlineinherited

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

◆ append() [1/2]

void axom::Array< T, DIM, MemorySpace::Dynamic >::append ( ArrayView< const T, DIM, OtherSpace >  other)
inlineinherited

Appends an Array to the end of the calling object.

Parameters
[in]otherThe Array to append
Template Parameters
OtherArrayTypeThe underlying type of the other array
Note
Reallocation is done if the new size will exceed the capacity.

◆ append() [2/2]

void axom::Array< T, DIM, MemorySpace::Dynamic >::append ( ArrayView< T, DIM, OtherSpace >  other)
inlineinherited

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

◆ erase() [1/2]

ArrayIterator axom::Array< T, DIM, MemorySpace::Dynamic >::erase ( ArrayIterator  pos)
inherited

Erases an element from the Array.

Parameters
[in]posthe ArrayIterator to the element in the Array
Returns
An ArrayIterator following the last element removed.

◆ erase() [2/2]

ArrayIterator axom::Array< T, DIM, MemorySpace::Dynamic >::erase ( ArrayIterator  first,
ArrayIterator  last 
)
inherited

Erases elements in the range [first, last) from the Array.

Parameters
[in]firstthe ArrayIterator to the beginning of the range.
[in]lastthe ArrayIterator to end of range.
Returns
An ArrayIterator following the last element removed.

◆ emplace() [1/3]

void axom::Array< T, DIM, MemorySpace::Dynamic >::emplace ( IndexType  pos,
Args &&...  args 
)
inlineinherited

Inserts new element into Array at the given position.

Parameters
[in]posthe position to insert element at.
[in]argsthe arguments to forward to constructor of the element.
Note
Reallocation is done if the new size will exceed the capacity.
The size increases by 1.
Precondition
T must be MoveAssignable

◆ emplace() [2/3]

ArrayIterator axom::Array< T, DIM, MemorySpace::Dynamic >::emplace ( ArrayIterator  pos,
Args &&...  args 
)
inherited

Inserts new element into Array before pos.

Parameters
[in]posthe ArrayIterator to insert element before.
[in]argsthe arguments to forward to constructor of the element.
Note
Reallocation is done if the new size will exceed the capacity.
The size increases by 1.
Precondition
T must be MoveAssignable
Returns
An ArrayIterator to the emplaced element.

◆ emplace() [3/3]

Array<T, DIM, MemorySpace::Dynamic >::ArrayIterator axom::Array< T, DIM, MemorySpace::Dynamic >::emplace ( Array< T, DIM, MemorySpace::Dynamic >::ArrayIterator  pos,
Args &&...  args 
)
inlineinherited

◆ push_back() [1/2]

void axom::Array< T, DIM, MemorySpace::Dynamic >::push_back ( const T &  value)
inlineinherited

Push a value to the back of the array.

Parameters
[in]valuethe value to be added to the back.
Note
Reallocation is done if the new size will exceed the capacity.
If used in a device kernel, the number of push_backs must not exceed the capacity, since device-side reallocations aren't supported.
Array must be allocated in unified memory if calling on the device.
Precondition
DIM == 1

◆ push_back() [2/2]

void axom::Array< T, DIM, MemorySpace::Dynamic >::push_back ( T &&  value)
inlineinherited

Push a value to the back of the array.

Parameters
[in]valuethe value to move to the back.
Note
Reallocation is done if the new size will exceed the capacity.
If used in a device kernel, the number of push_backs must not exceed the capacity, since device-side reallocations aren't supported.
Array must be allocated in unified memory if calling on the device.
Precondition
DIM == 1

◆ emplace_back()

void axom::Array< T, DIM, MemorySpace::Dynamic >::emplace_back ( Args &&...  args)
inlineinherited

Inserts new element at the end of the Array.

Parameters
[in]argsthe arguments to forward to constructor of the element.
Note
Reallocation is done if the new size will exceed the capacity.
The size increases by 1.
If used in a device kernel, the number of push_backs must not exceed the capacity, since device-side reallocations aren't supported.
Array must be allocated in unified memory if calling on the device.
Precondition
DIM == 1

◆ capacity()

IndexType axom::Array< T, DIM, MemorySpace::Dynamic >::capacity ( ) const
inlineinherited

Return the number of elements allocated for the data array.

◆ reserve()

void axom::Array< T, DIM, MemorySpace::Dynamic >::reserve ( IndexType  capacity)
inlineinherited

Increase the capacity. Does nothing if the new capacity is less than the current capacity.

Parameters
[in]capacitythe new number of elements to allocate.

◆ begin() [1/2]

ArrayIterator axom::Array< T, DIM, MemorySpace::Dynamic >::begin ( )
inlineinherited

Returns an ArrayIterator to the first element of the Array.

◆ begin() [2/2]

ConstArrayIterator axom::Array< T, DIM, MemorySpace::Dynamic >::begin ( ) const
inlineinherited

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

◆ end() [1/2]

ArrayIterator axom::Array< T, DIM, MemorySpace::Dynamic >::end ( )
inlineinherited

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

◆ end() [2/2]

ConstArrayIterator axom::Array< T, DIM, MemorySpace::Dynamic >::end ( ) const
inlineinherited

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

◆ front() [1/2]

T& axom::Array< T, DIM, MemorySpace::Dynamic >::front ( )
inlineinherited

Returns a reference to the first element in the Array.

Precondition
array.empty() == false

◆ front() [2/2]

const T& axom::Array< T, DIM, MemorySpace::Dynamic >::front ( ) const
inlineinherited

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

◆ back() [1/2]

T& axom::Array< T, DIM, MemorySpace::Dynamic >::back ( )
inlineinherited

Returns a reference to the last element in the Array.

Precondition
array.size() > 0

◆ back() [2/2]

const T& axom::Array< T, DIM, MemorySpace::Dynamic >::back ( ) const
inlineinherited

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

◆ shrink()

void axom::Array< T, DIM, MemorySpace::Dynamic >::shrink ( )
inlineinherited

Shrink the capacity to be equal to the size.

◆ empty()

bool axom::Array< T, DIM, MemorySpace::Dynamic >::empty ( ) const
inlineinherited

Returns true iff the Array stores no elements.

Note
If the Array is empty the capacity can still be greater than zero.

◆ size()

IndexType axom::Array< T, DIM, MemorySpace::Dynamic >::size ( ) const
inlineinherited

Return the number of elements stored in the data array.

◆ resize() [1/4]

void axom::Array< T, DIM, MemorySpace::Dynamic >::resize ( Args...  args)
inlineinherited

Update the number of elements stored in the data array.

Note
Reallocation is done if the new size will exceed the capacity.

◆ resize() [2/4]

void axom::Array< T, DIM, MemorySpace::Dynamic >::resize ( ArrayOptions::Uninitialized  ,
Args...  args 
)
inlineinherited

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

◆ resize() [3/4]

void axom::Array< T, DIM, MemorySpace::Dynamic >::resize ( IndexType  size,
const T &  value 
)
inlineinherited

◆ resize() [4/4]

void axom::Array< T, DIM, MemorySpace::Dynamic >::resize ( const StackArray< IndexType, DIM > &  size,
const T &  value 
)
inlineinherited

◆ swap() [1/2]

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

Exchanges the contents of this Array with the other.

◆ swap() [2/2]

template<typename T , int DIM, typename ArrayType >
void axom::ArrayBase< T, DIM, ArrayType >::swap ( ArrayBase< T, DIM, ArrayType > &  other)
inlineinherited

◆ getResizeRatio()

double axom::Array< T, DIM, MemorySpace::Dynamic >::getResizeRatio ( ) const
inlineinherited

Get the ratio by which the capacity increases upon dynamic resize.

◆ setResizeRatio()

void axom::Array< T, DIM, MemorySpace::Dynamic >::setResizeRatio ( double  ratio)
inlineinherited

Set the ratio by which the capacity increases upon dynamic resize.

Parameters
[in]ratiothe new resize ratio.

◆ getAllocatorID()

int axom::Array< T, DIM, MemorySpace::Dynamic >::getAllocatorID ( ) const
inlineinherited

Get the ID for the umpire allocator.

◆ view() [1/2]

ArrayViewType axom::Array< T, DIM, MemorySpace::Dynamic >::view ( )
inlineinherited

Returns a view of the array.

See also
ArrayView

◆ view() [2/2]

ConstArrayViewType axom::Array< T, DIM, MemorySpace::Dynamic >::view ( ) const
inlineinherited

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

◆ initialize()

void axom::Array< T, DIM, MemorySpace::Dynamic >::initialize ( IndexType  num_elements,
IndexType  capacity,
bool  should_default_construct = true 
)
inlineprotectedinherited

Initialize an Array instance with the given number of elements.

Parameters
[in]num_elementsthe number of elements the Array holds.
[in]capacitythe number of elements to allocate space for.
[in]should_default_constructwhether to create default-constructed objects in the region [0, num_elements). Defaults to true.
Note
If no capacity or capacity less than num_elements is specified then it will default to at least num_elements * DEFAULT_RESIZE_RATIO.
a capacity is specified for the number of elements to store in the array and does not correspond to the actual bytesize.
Precondition
num_elements >= 0
Postcondition
capacity() >= size()
size() == num_elements
getResizeRatio() == DEFAULT_RESIZE_RATIO

◆ initialize_from_other()

void axom::Array< T, DIM, MemorySpace::Dynamic >::initialize_from_other ( const T *  data,
IndexType  num_elements,
MemorySpace  data_space,
bool  user_provided_allocator 
)
inlineprotectedinherited

Helper function for initializing an Array instance with an existing range of elements.

Parameters
[in]datapointer to the existing array of elements
[in]num_elementsthe number of elements in the existing array
[in]data_spacethe memory space in which data has been allocated
[in]user_provided_allocatortrue if the Array's allocator ID was provided by the user

◆ resizeImpl()

void axom::Array< T, DIM, MemorySpace::Dynamic >::resizeImpl ( const StackArray< IndexType, DIM > &  dims,
bool  construct_with_values,
const T *  value = nullptr 
)
inlineprotectedinherited

Updates the number of elements stored in the data array.

Parameters
[in]dimsthe number of elements to allocate in each dimension
[in]construct_with_valuesif true, sets new elements in the array to a specified value
[in]valuepointer to the value to fill new elements in the array with. If null, will default-construct elements in place.

◆ reserveForInsert()

T * axom::Array< T, DIM, MemorySpace::Dynamic >::reserveForInsert ( IndexType  n,
IndexType  pos 
)
inlineprotectedinherited

Make space for a subsequent insertion into the array.

Parameters
[in]nthe number of elements to insert.
[in]posthe position at which to begin the insertion.
Returns
a pointer to the beginning of the insertion space.
Note
Reallocation is done if the new size will exceed the capacity.

◆ reserveForDeviceInsert()

IndexType axom::Array< T, DIM, MemorySpace::Dynamic >::reserveForDeviceInsert ( IndexType  n)
inlineprotectedinherited

Make space for a subsequent insertion into the array.

Parameters
[in]nthe number of elements to insert.
Note
This version supports concurrent GPU insertions.
Reallocation is not supported.

◆ updateNumElements()

void axom::Array< T, DIM, MemorySpace::Dynamic >::updateNumElements ( IndexType  new_num_elements)
inlineprotectedvirtualinherited

Update the number of elements.

Parameters
[in]new_num_elementsthe new number of elements.

Reimplemented in axom::sidre::Array< T, DIM >.

◆ operator()() [1/2]

template<typename T , int DIM, typename ArrayType >
template<typename... Args>
AXOM_HOST_DEVICE SliceType<sizeof...(Args)> axom::ArrayBase< T, DIM, ArrayType >::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]

template<typename T , int DIM, typename ArrayType >
template<typename... Args>
AXOM_HOST_DEVICE ConstSliceType<sizeof...(Args)> axom::ArrayBase< T, DIM, ArrayType >::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]

template<typename T , int DIM, typename ArrayType >
AXOM_HOST_DEVICE SliceType<1> axom::ArrayBase< T, DIM, ArrayType >::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]

template<typename T , int DIM, typename ArrayType >
AXOM_HOST_DEVICE ConstSliceType<1> axom::ArrayBase< T, DIM, ArrayType >::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]

template<typename T , int DIM, typename ArrayType >
template<int UDim>
AXOM_HOST_DEVICE SliceType<UDim> axom::ArrayBase< T, DIM, ArrayType >::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]

template<typename T , int DIM, typename ArrayType >
template<int UDim>
AXOM_HOST_DEVICE ConstSliceType<UDim> axom::ArrayBase< T, DIM, ArrayType >::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]

template<typename T , int DIM, typename ArrayType >
AXOM_HOST_DEVICE T& axom::ArrayBase< T, DIM, ArrayType >::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]

template<typename T , int DIM, typename ArrayType >
AXOM_HOST_DEVICE RealConstT& axom::ArrayBase< T, DIM, ArrayType >::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.

◆ shape()

template<typename T , int DIM, typename ArrayType >
AXOM_HOST_DEVICE const StackArray<IndexType, DIM>& axom::ArrayBase< T, DIM, ArrayType >::shape ( ) const
inlineinherited

Returns the dimensions of the Array.

References axom::ArrayBase< T, DIM, ArrayType >::m_shape.

◆ strides()

template<typename T , int DIM, typename ArrayType >
AXOM_HOST_DEVICE const StackArray<IndexType, DIM>& axom::ArrayBase< T, DIM, ArrayType >::strides ( ) const
inlineinherited

Returns the memory strides of the Array.

References axom::ArrayBase< T, DIM, ArrayType >::m_strides.

◆ minStride()

template<typename T , int DIM, typename ArrayType >
AXOM_HOST_DEVICE IndexType axom::ArrayBase< T, DIM, ArrayType >::minStride ( ) const
inlineinherited

Returns the minimum stride between adjacent items.

References axom::ArrayBase< T, DIM, ArrayType >::m_strides, and axom::utilities::min().

◆ setShape()

template<typename T , int DIM, typename ArrayType >
AXOM_HOST_DEVICE void axom::ArrayBase< T, DIM, ArrayType >::setShape ( const StackArray< IndexType, DIM > &  shape_)
inlineprotectedinherited

◆ setShapeAndStride()

template<typename T , int DIM, typename ArrayType >
AXOM_HOST_DEVICE void axom::ArrayBase< T, DIM, ArrayType >::setShapeAndStride ( const StackArray< IndexType, DIM > &  shape,
const StackArray< IndexType, DIM > &  stride 
)
inlineprotectedinherited

◆ blockSize()

template<typename T , int DIM, typename ArrayType >
IndexType axom::ArrayBase< T, DIM, ArrayType >::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.

References axom::ArrayBase< T, DIM, ArrayType >::m_strides.

◆ updateStrides()

template<typename T , int DIM, typename ArrayType >
AXOM_HOST_DEVICE void axom::ArrayBase< T, DIM, ArrayType >::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.

References axom::ArrayBase< T, DIM, ArrayType >::m_shape, and axom::ArrayBase< T, DIM, ArrayType >::m_strides.

◆ updateShapeOnInsert()

template<typename T , int DIM, typename ArrayType >
void axom::ArrayBase< T, DIM, ArrayType >::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.

References axom::StackArray< T, N >::begin(), axom::StackArray< T, N >::end(), axom::ArrayBase< T, DIM, ArrayType >::m_shape, axom::utilities::processAbort(), and axom::ArrayBase< T, DIM, ArrayType >::updateStrides().

Member Data Documentation

◆ DEFAULT_RESIZE_RATIO

constexpr double axom::Array< T, DIM, MemorySpace::Dynamic >::DEFAULT_RESIZE_RATIO
staticconstexprinherited

◆ MIN_DEFAULT_CAPACITY

constexpr IndexType axom::Array< T, DIM, MemorySpace::Dynamic >::MIN_DEFAULT_CAPACITY
staticconstexprinherited

◆ space

constexpr MemorySpace axom::Array< T, DIM, MemorySpace::Dynamic >::space
staticconstexprinherited

◆ m_data

T* axom::Array< T, DIM, MemorySpace::Dynamic >::m_data
protectedinherited

◆ m_num_elements

IndexType axom::Array< T, DIM, MemorySpace::Dynamic >::m_num_elements
protectedinherited

The full number of elements in the array i.e., 3 for a 1D Array of size 3, 9 for a 3x3 2D array, etc.

◆ m_capacity

IndexType axom::Array< T, DIM, MemorySpace::Dynamic >::m_capacity
protectedinherited

◆ m_resize_ratio

double axom::Array< T, DIM, MemorySpace::Dynamic >::m_resize_ratio
protectedinherited

◆ m_allocator_id

int axom::Array< T, DIM, MemorySpace::Dynamic >::m_allocator_id
protectedinherited

◆ Dims

template<typename T , int DIM, typename ArrayType >
constexpr static int axom::ArrayBase< T, DIM, ArrayType >::Dims = DIM
staticconstexprinherited

◆ m_shape

template<typename T , int DIM, typename ArrayType >
StackArray<IndexType, DIM> axom::ArrayBase< T, DIM, ArrayType >::m_shape
protectedinherited

The extent in each direction.

◆ m_strides

template<typename T , int DIM, typename ArrayType >
StackArray<IndexType, DIM> axom::ArrayBase< T, DIM, ArrayType >::m_strides
protectedinherited

Logical strides in each direction.


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