AXOM
Axom provides a robust, flexible software infrastructure for the development of multi-physics applications and computational tools.
|
Provides a generic multidimensional array container. More...
#include </home/docs/checkouts/readthedocs.org/user_builds/axom/checkouts/v0.6.1/src/axom/core/Array.hpp>
Public Types | |
using | value_type = T |
using | ArrayIterator = ArrayIteratorBase< Array< T, DIM, SPACE > > |
Public Member Functions | |
virtual | ~Array () |
template<typename... Args> | |
Array< T, DIM, SPACE >::ArrayIterator | emplace (Array< T, DIM, SPACE >::ArrayIterator pos, Args &&... args) |
template<typename T , int DIM> | |
Array (Array< T, DIM > &&other) | |
AXOM_HOST_DEVICE T & | operator() (Args... args) |
Dimension-aware accessor, returns a reference to the given value. More... | |
AXOM_HOST_DEVICE const T & | operator() (Args... args) const |
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 strides of the Array. More... | |
void | insert (IndexType pos, const ArrayBase< T, DIM, OtherArrayType > &other) |
Appends an Array to the end of the calling object. More... | |
Native Storage Array Constructors | |
Array () | |
Default constructor. Constructs an Array instance with no elements and default allocator ID. More... | |
template<IndexType SFINAE_DIM = DIM, MemorySpace SFINAE_SPACE = SPACE, typename std::enable_if< SFINAE_DIM==1 &&SFINAE_SPACE==MemorySpace::Dynamic >::type * = nullptr> | |
Array (IndexType num_elements, IndexType capacity=0, int allocator_id=axom::detail::getAllocatorID< SPACE >()) | |
Constructs a 1D Array instance with the given number of elements. More... | |
template<IndexType SFINAE_DIM = DIM, MemorySpace SFINAE_SPACE = SPACE, typename std::enable_if< SFINAE_DIM==1 &&SFINAE_SPACE !=MemorySpace::Dynamic >::type * = nullptr> | |
Array (IndexType num_elements, IndexType capacity=0) | |
template<typename... Args, typename std::enable_if< detail::all_types_are_integral< Args... >::value >::type * = nullptr> | |
Array (Args... args) | |
Generic constructor for an Array of arbitrary dimension. More... | |
Array (const Array &other, int allocator_id=axom::detail::getAllocatorID< SPACE >()) | |
Copy constructor for an Array instance. More... | |
Array (Array &&other) | |
Move constructor for an Array instance. More... | |
template<typename OtherArrayType > | |
Array (const ArrayBase< T, DIM, OtherArrayType > &other) | |
Constructor for transferring between memory spaces. More... | |
Array copy and move operators | |
Array & | operator= (const Array &other) |
Copy assignment operator for Array. More... | |
Array & | operator= (Array &&other) |
Move assignment operator for Array. 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 | 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... | |
template<typename OtherArrayType > | |
void | append (const ArrayBase< T, DIM, OtherArrayType > &other) |
Appends an Array to the end of the calling object. 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... | |
template<typename... Args> | |
void | emplace (IndexType pos, Args &&... args) |
Inserts new element into Array at the given position. More... | |
template<typename... Args> | |
ArrayIterator | emplace (ArrayIterator pos, Args &&... args) |
Inserts new element into Array before pos. 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... | |
ArrayIterator | end () |
Returns an ArrayIterator to the element following the last element of the Array. 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... | |
template<typename... Args> | |
void | resize (Args... args) |
Update the number of elements stored in the data array. More... | |
void | swap (Array< T, DIM, SPACE > &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... | |
AXOM_HOST_DEVICE T & | operator[] (const IndexType idx) |
Accessor, returns a reference to the given value. For multidimensional arrays, indexes into the (flat) raw data. More... | |
AXOM_HOST_DEVICE const T & | operator[] (const IndexType idx) const |
Static Public Attributes | |
static constexpr double | DEFAULT_RESIZE_RATIO = 2.0 |
static constexpr IndexType | MIN_DEFAULT_CAPACITY = 32 |
static constexpr MemorySpace | space = SPACE |
Protected Member Functions | |
void | initialize (IndexType num_elements, IndexType capacity) |
Initialize an Array instance with the given number of elements. More... | |
T * | reserveForInsert (IndexType n, IndexType pos) |
Make space for a subsequent insertion into the array. More... | |
virtual void | updateNumElements (IndexType new_num_elements) |
Update the number of elements. More... | |
virtual void | setCapacity (IndexType new_capacity) |
Set the number of elements allocated for the data array. More... | |
virtual void | dynamicRealloc (IndexType new_num_elements) |
Reallocates the data array when the size exceeds the capacity. 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... | |
void | updateStrides () |
Updates the internal striding information to a row-major format Intended to be called after m_dims is updated. In the future, this class will support different striding schemes (e.g., column-major) and/or user-provided striding. More... | |
Protected Attributes | |
T * | m_data = nullptr |
IndexType | m_num_elements = 0 |
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 = 0 |
double | m_resize_ratio = DEFAULT_RESIZE_RATIO |
int | m_allocator_id |
StackArray< IndexType, DIM > | m_dims |
The sizes (extents?) in each dimension. More... | |
StackArray< IndexType, DIM > | m_strides |
The strides in each dimension. More... | |
Provides a generic multidimensional array container.
The Array class provides a generic multidimensional array container with dynamic reallocation and insertion. The dimensionality of the array must be known at compile time but the extents in each dimension are dynamic and can be changed at runtime. Array elements are stored contiguously.
The Array class mirrors std::vector, with future support for GPUs in-development. The class's multidimensional array functionality roughly mirrors the multidimensional array support provided by numpy's ndarray.
This class is meant to be a drop-in replacement for std::vector. However, it differs in its memory management and construction semantics. Specifically, we do not require axom::Array to initialize/construct its memory at allocation time and we use axom's memory_management and allocator ID abstractions rather than std::allocator.
Array always retains exclusive ownership of its data and is responsible for freeing its memory.
T | the type of the values to hold. |
DIM | The dimension of the array. |
using axom::Array< T, DIM, SPACE >::value_type = T |
using axom::Array< T, DIM, SPACE >::ArrayIterator = ArrayIteratorBase<Array<T, DIM, SPACE> > |
axom::Array< T, DIM, SPACE >::Array | ( | ) |
Default constructor. Constructs an Array instance with no elements and default allocator ID.
axom::Array< T, DIM, SPACE >::Array | ( | IndexType | num_elements, |
IndexType | capacity = 0 , |
||
int | allocator_id = axom::detail::getAllocatorID<SPACE>() |
||
) |
Constructs a 1D Array instance with the given number of elements.
[in] | num_elements | the number of elements the Array holds. |
[in] | capacity | the number of elements to allocate space for. |
[in] | allocator_id | the ID of the allocator to use (optional) |
axom::Array< T, DIM, SPACE >::Array | ( | IndexType | num_elements, |
IndexType | capacity = 0 |
||
) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
axom::Array< T, DIM, SPACE >::Array | ( | Args... | args | ) |
Generic constructor for an Array of arbitrary dimension.
[in] | args | The parameter pack containing the "shape" of the Array |
axom::Array< T, DIM, SPACE >::Array | ( | const Array< T, DIM, SPACE > & | other, |
int | allocator_id = axom::detail::getAllocatorID<SPACE>() |
||
) |
Copy constructor for an Array instance.
[in] | allocator_id | the ID of the allocator to use (optional) |
axom::Array< T, DIM, SPACE >::Array | ( | Array< T, DIM, SPACE > && | other | ) |
Move constructor for an Array instance.
axom::Array< T, DIM, SPACE >::Array | ( | const ArrayBase< T, DIM, OtherArrayType > & | other | ) |
Constructor for transferring between memory spaces.
[in] | other | The array in a different memory space to copy from |
|
virtual |
Destructor. Frees the associated buffer.
Reimplemented in axom::sidre::Array< T, DIM >.
Referenced by axom::Array< T, DIM >::operator=().
axom::Array< T, DIM, SPACE >::Array | ( | Array< T, DIM > && | other | ) |
|
inline |
Copy assignment operator for Array.
Referenced by axom::Array< T, DIM >::Array().
|
inline |
Move assignment operator for Array.
|
inline |
Return a pointer to the array of data.
Referenced by axom::Array< T, DIM >::Array(), and axom::Array< T, DIM >::operator=().
|
inline |
|
inline |
Set all the values of the array.
[in] | value | the value to set to. |
Referenced by axom::Array< T, DIM >::data().
|
inline |
Modify the values of existing elements.
[in] | elements | the new elements to write. |
[in] | n | the number of elements to write. |
[in] | pos | the position at which to begin writing. |
|
inline |
Clears the contents of the array.
Referenced by axom::Array< T, DIM >::data().
|
inline |
Insert an element into the array at the given position.
[in] | pos | the position at which to insert. |
[in] | value | the element value to insert. |
Referenced by axom::Array< T, DIM >::append(), and axom::Array< T, DIM >::data().
ArrayIterator axom::Array< T, DIM, SPACE >::insert | ( | ArrayIterator | pos, |
const T & | value | ||
) |
Insert an element into the array at the value before pos.
[in] | pos | the ArrayIterator before which value will be inserted. |
[in] | value | the element value to insert. |
|
inline |
Insert elements into the array at the given position.
[in] | pos | the position at which to begin the insertion. |
[in] | n | the number of elements to insert. |
[in] | values | the element values to insert. |
ArrayIterator axom::Array< T, DIM, SPACE >::insert | ( | ArrayIterator | pos, |
IndexType | n, | ||
const T * | values | ||
) |
Insert elements into the array at the value before pos.
[in] | pos | the ArrayIterator before which value will be inserted. |
[in] | n | the number of elements to insert. |
[in] | values | the element values to insert. |
|
inline |
Insert n copies of element into the array at the given position.
[in] | pos | the position at which to begin the insertion. |
[in] | n | the number of elements to insert. |
[in] | value | the element value to insert. |
ArrayIterator axom::Array< T, DIM, SPACE >::insert | ( | ArrayIterator | pos, |
IndexType | n, | ||
const T & | value | ||
) |
Insert n copies of element into the array at the value before pos.
[in] | pos | the ArrayIterator before which value will be inserted. |
[in] | n | the number of elements to insert. |
[in] | value | the element value to insert. |
|
inline |
ArrayIterator axom::Array< T, DIM, SPACE >::erase | ( | ArrayIterator | pos | ) |
Erases an element from the Array.
[in] | pos | the ArrayIterator to the element in the Array |
Referenced by axom::Array< T, DIM >::append().
ArrayIterator axom::Array< T, DIM, SPACE >::erase | ( | ArrayIterator | first, |
ArrayIterator | last | ||
) |
Erases elements in the range [first, last) from the Array.
[in] | first | the ArrayIterator to the beginning of the range. |
[in] | last | the ArrayIterator to end of range. |
|
inline |
Inserts new element into Array at the given position.
[in] | pos | the position to insert element at. |
[in] | args | the arguments to forward to constructor of the element. |
Referenced by axom::Array< T, DIM >::append().
ArrayIterator axom::Array< T, DIM, SPACE >::emplace | ( | ArrayIterator | pos, |
Args &&... | args | ||
) |
Inserts new element into Array before pos.
[in] | pos | the ArrayIterator to insert element before. |
[in] | args | the arguments to forward to constructor of the element. |
|
inline |
Return the number of elements allocated for the data array.
Referenced by axom::Array< T, DIM >::Array(), axom::Array< T, DIM >::getAllocatorID(), and axom::Array< T, DIM >::operator=().
|
inline |
Increase the capacity. Does nothing if the new capacity is less than the current capacity.
[in] | capacity | the new number of elements to allocate. |
|
inline |
Returns an ArrayIterator to the first element of the Array.
|
inline |
Returns an ArrayIterator to the element following the last element of the Array.
|
inline |
Shrink the capacity to be equal to the size.
|
inline |
|
inline |
Return the number of elements stored in the data array.
Referenced by axom::Array< T, DIM >::append(), axom::Array< T, DIM >::Array(), axom::Array< T, DIM >::end(), and axom::Array< T, DIM >::operator=().
|
inline |
Update the number of elements stored in the data array.
Referenced by axom::Array< T, DIM >::size().
|
inline |
Exchanges the contents of this Array with the other.
Referenced by axom::Array< T, DIM >::size().
|
inline |
Get the ratio by which the capacity increases upon dynamic resize.
|
inline |
Set the ratio by which the capacity increases upon dynamic resize.
[in] | ratio | the new resize ratio. |
|
inline |
Get the ID for the umpire allocator.
|
inlineprotected |
Initialize an Array instance with the given number of elements.
[in] | num_elements | the number of elements the Array holds. |
[in] | capacity | the number of elements to allocate space for. |
Referenced by axom::Array< T, DIM >::getAllocatorID(), and axom::Array< T, DIM >::operator=().
|
inlineprotected |
Make space for a subsequent insertion into the array.
[in] | n | the number of elements to insert. |
[in] | pos | the position at which to begin the insertion. |
Referenced by axom::Array< T, DIM >::getAllocatorID().
|
inlineprotectedvirtual |
Update the number of elements.
[in] | new_num_elements | the new number of elements. |
Reimplemented in axom::sidre::Array< T, DIM >.
Referenced by axom::Array< T, DIM >::getAllocatorID().
|
inlineprotectedvirtual |
Set the number of elements allocated for the data array.
[in] | capacity | the new number of elements to allocate. |
Reimplemented in axom::sidre::Array< T, DIM >.
Referenced by axom::Array< T, DIM >::getAllocatorID(), axom::Array< T, DIM >::reserve(), and axom::Array< T, DIM >::shrink().
|
inlineprotectedvirtual |
Reallocates the data array when the size exceeds the capacity.
[in] | new_num_elements | the number of elements which exceeds the current capacity. |
Reimplemented in axom::sidre::Array< T, DIM >.
Referenced by axom::Array< T, DIM >::getAllocatorID().
|
inline |
|
inlineinherited |
Dimension-aware accessor, returns a reference to the given value.
[in] | args | the parameter pack of indices in each dimension. |
|
inlineinherited |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
|
inlineinherited |
Accessor, returns a reference to the given value. For multidimensional arrays, indexes into the (flat) raw data.
[in] | idx | the position of the value to return. |
|
inlineinherited |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
|
inlineinherited |
Returns the dimensions of the Array.
|
inlineinherited |
Returns the strides of the Array.
|
inlineinherited |
|
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.
|
inlineprotectedinherited |
Updates the internal striding information to a row-major format Intended to be called after m_dims
is updated. In the future, this class will support different striding schemes (e.g., column-major) and/or user-provided striding.
|
static |
Referenced by axom::Array< T, DIM >::operator=().
|
static |
|
static |
|
protected |
|
protected |
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.
Referenced by axom::Array< T, DIM >::empty(), axom::Array< T, DIM >::operator=(), axom::Array< T, DIM >::shrink(), axom::Array< T, DIM >::size(), and axom::Array< T, DIM >::swap().
|
protected |
|
protected |
|
protected |
Referenced by axom::Array< T, DIM >::getAllocatorID(), and axom::Array< T, DIM >::operator=().
|
protectedinherited |
The sizes (extents?) in each dimension.
|
protectedinherited |
The strides in each dimension.