Provides a generic multidimensional array container. More...

#include </home/docs/checkouts/readthedocs.org/user_builds/axom/checkouts/v0.6.0/src/axom/core/Array.hpp>

Inheritance diagram for axom::Array< T, DIM >:

Public Types
using	value_type = T

using	ArrayIterator = ArrayIteratorBase< Array< T, DIM > >

Public Member Functions
virtual	~Array ()

template<IndexType SFINAE, typename std::enable_if< SFINAE==1 >::type * >
Array< T, DIM >::ArrayIterator	insert (Array< T, DIM >::ArrayIterator pos, const T &value)

template<IndexType SFINAE, typename std::enable_if< SFINAE==1 >::type * >
Array< T, DIM >::ArrayIterator	insert (Array< T, DIM >::ArrayIterator pos, IndexType n, const T *values)

template<IndexType SFINAE, typename std::enable_if< SFINAE==1 >::type * >
Array< T, DIM >::ArrayIterator	insert (Array< T, DIM >::ArrayIterator pos, IndexType n, const T &value)

template<typename... Args>
Array< T, DIM >::ArrayIterator	emplace (Array< T, DIM >::ArrayIterator pos, Args &&... args)

T &	operator() (Args... args)
	Dimension-aware accessor, returns a reference to the given value. More...

const T &	operator() (Args... args) const

const std::array< IndexType, DIM > &	shape () const
	Returns the dimensions of the Array. More...

const std::array< 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, typename std::enable_if< SFINAE==1 >::type * = nullptr>
	Array (IndexType num_elements, IndexType capacity=0, int allocator_id=axom::getDefaultAllocatorID())
	Constructs a 1D Array instance with the given number of elements. More...

template<typename... Args>
	Array (Args... args)
	Generic constructor for an Array of arbitrary dimension. More...

	Array (const Array &other, int allocator_id=axom::getDefaultAllocatorID())
	Copy constructor for an Array instance. More...

	Array (Array &&other)
	Move constructor for an Array instance. 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...

template<IndexType SFINAE = DIM, typename std::enable_if< SFINAE==1 >::type * = nullptr>
void	insert (IndexType pos, const T &value)
	Insert an element into the array at the given position. More...

template<IndexType SFINAE = DIM, typename std::enable_if< SFINAE==1 >::type * = nullptr>
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...

template<IndexType SFINAE = DIM, typename std::enable_if< SFINAE==1 >::type * = nullptr>
ArrayIterator	insert (ArrayIterator pos, IndexType n, const T *values)
	Insert elements into the array at the value before pos. More...

template<IndexType SFINAE = DIM, typename std::enable_if< SFINAE==1 >::type * = nullptr>
void	insert (IndexType pos, IndexType n, const T &value)
	Insert n copies of element into the array at the given position. More...

template<IndexType SFINAE = DIM, typename std::enable_if< SFINAE==1 >::type * = nullptr>
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 > &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...


T &	operator[] (const IndexType idx)
	Accessor, returns a reference to the given value. For multidimensional arrays, indexes into the (flat) raw data. More...

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

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

std::array< IndexType, DIM >	m_dims
	The sizes (extents?) in each dimension. More...

std::array< IndexType, DIM >	m_strides
	The strides in each dimension. More...

Detailed Description

template<typename T, int DIM = 1>
class axom::Array< T, DIM >

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.

Note: For a multi-component array container, where each element is a tuple of 1 or more components, Axom provides the MCArray alias, which corresponds to Array<T, 2>.

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.

See also: https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html

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.

See also: ArrayView for non-owning views of one- or multi-dimensional data Depending on which constructor is used, the Array object can have two different underlying storage types:

Template Parameters

T	the type of the values to hold.
DIM	The dimension of the array.

Precondition: T must be CopyAssignable and Erasable

See also: https://en.cppreference.com/w/cpp/named_req

Member Typedef Documentation

◆ value_type

template<typename T, int DIM = 1>

using axom::Array< T, DIM >::value_type = T

◆ ArrayIterator

template<typename T, int DIM = 1>

using axom::Array< T, DIM >::ArrayIterator = ArrayIteratorBase<Array<T, DIM> >

Constructor & Destructor Documentation

◆ Array() [1/5]

template<typename T , int DIM>

axom::Array< T, DIM >::Array ( )

Default constructor. Constructs an Array instance with no elements and default allocator ID.

◆ Array() [2/5]

template<typename T , int DIM>

template<IndexType SFINAE, typename std::enable_if< SFINAE==1 >::type * >

axom::Array< T, DIM >::Array	(	IndexType	num_elements,
		IndexType	capacity = `0`,
		int	allocator_id = `axom::getDefaultAllocatorID()`
	)

Constructs a 1D Array instance with the given number of elements.

Parameters

[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)

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.; The option to select a capacity is only available for 1-dimensional Arrays

Precondition: num_elements >= 0

Postcondition: capacity() >= size(); size() == num_elements; getResizeRatio() == DEFAULT_RESIZE_RATIO

References axom::Array< T, DIM >::initialize().

◆ Array() [3/5]

template<typename T , int DIM>

template<typename... Args>

axom::Array< T, DIM >::Array ( Args... args )

Generic constructor for an Array of arbitrary dimension.

Parameters

[in] args The parameter pack containing the "shape" of the Array

See also: https://numpy.org/doc/stable/reference/generated/numpy.empty.html#numpy.empty

Precondition: sizeof...(Args) == DIM

Postcondition: capacity() >= size(); size() == num_elements; getResizeRatio() == DEFAULT_RESIZE_RATIO

References axom::detail::allNonNegative(), axom::Array< T, DIM >::initialize(), and axom::detail::packProduct().

◆ Array() [4/5]

template<typename T , int DIM>

axom::Array< T, DIM >::Array	(	const Array< T, DIM > &	other,
		int	allocator_id = `axom::getDefaultAllocatorID()`
	)

Copy constructor for an Array instance.

Parameters

[in] allocator_id the ID of the allocator to use (optional)

References axom::Array< T, DIM >::capacity(), axom::copy(), axom::Array< T, DIM >::data(), axom::Array< T, DIM >::initialize(), axom::Array< T, DIM >::m_data, axom::Array< T, DIM >::m_num_elements, and axom::Array< T, DIM >::size().

◆ Array() [5/5]

template<typename T , int DIM>

axom::Array< T, DIM >::Array ( Array< T, DIM > && other )

Move constructor for an Array instance.

References axom::Array< T, DIM >::DEFAULT_RESIZE_RATIO, axom::INVALID_ALLOCATOR_ID, axom::Array< T, DIM >::m_allocator_id, axom::Array< T, DIM >::m_capacity, axom::Array< T, DIM >::m_data, axom::Array< T, DIM >::m_num_elements, and axom::Array< T, DIM >::m_resize_ratio.

◆ ~Array()

template<typename T , int DIM>

axom::Array< T, DIM >::~Array ( )

virtual

Destructor. Frees the associated buffer.

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

References axom::deallocate(), and axom::Array< T, DIM >::m_data.

Referenced by axom::Array< T, DIM >::operator=().

Member Function Documentation

◆ operator=() [1/2]

template<typename T, int DIM = 1>

Array& axom::Array< T, DIM >::operator= ( const Array< T, DIM > & other )

inline

Copy assignment operator for Array.

Note: The data will be allocated using the allocator ID of the copy-assigned Array, not the argument Array.

Precondition: T must be TriviallyCopyable

References axom::Array< T, DIM >::capacity(), axom::copy(), axom::Array< T, DIM >::data(), axom::Array< T, DIM >::initialize(), axom::Array< T, DIM >::m_data, axom::Array< T, DIM >::m_num_elements, axom::Array< T, DIM >::m_resize_ratio, and axom::Array< T, DIM >::size().

Referenced by axom::sidre::Array< T, DIM >::operator=().

◆ operator=() [2/2]

template<typename T, int DIM = 1>

Array& axom::Array< T, DIM >::operator= ( Array< T, DIM > && other )

inline

Move assignment operator for Array.

References axom::deallocate(), axom::Array< T, DIM >::DEFAULT_RESIZE_RATIO, axom::INVALID_ALLOCATOR_ID, axom::Array< T, DIM >::m_allocator_id, axom::Array< T, DIM >::m_capacity, axom::Array< T, DIM >::m_data, axom::Array< T, DIM >::m_num_elements, axom::Array< T, DIM >::m_resize_ratio, and axom::Array< T, DIM >::~Array().

◆ data() [1/2]

template<typename T, int DIM = 1>

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

inline

Return a pointer to the array of data.

References axom::Array< T, DIM >::m_data.

Referenced by axom::Array< T, DIM >::Array(), and axom::Array< T, DIM >::operator=().

◆ data() [2/2]

template<typename T, int DIM = 1>

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

inline

References axom::Array< T, DIM >::clear(), axom::Array< T, DIM >::fill(), axom::Array< T, DIM >::insert(), and axom::Array< T, DIM >::m_data.

◆ fill()

template<typename T, int DIM>

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

inline

Set all the values of the array.

Parameters

[in] value the value to set to.

References axom::Array< T, DIM >::m_data, and axom::Array< T, DIM >::m_num_elements.

Referenced by axom::Array< T, DIM >::data().

◆ set()

template<typename T, int DIM>

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

inline

Modify the values of existing elements.

Parameters

[in]	elements	the new elements to write.
[in]	n	the number of elements to write.
[in]	pos	the 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.

References axom::Array< T, DIM >::m_data, and axom::Array< T, DIM >::m_num_elements.

◆ clear()

template<typename T , int DIM>

void axom::Array< T, DIM >::clear ( )

inline

Clears the contents of the array.

Postcondition: size of Array is 0; capacity is unchanged

References axom::Array< T, DIM >::m_data, axom::Array< T, DIM >::m_num_elements, and axom::Array< T, DIM >::updateNumElements().

Referenced by axom::Array< T, DIM >::data().

◆ insert() [1/10]

template<typename T, int DIM>

template<IndexType SFINAE, typename std::enable_if< SFINAE==1 >::type * >

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

inline

Insert an element into the array at the given position.

Parameters

[in]	pos	the position at which to insert.
[in]	value	the element value to insert.

Note: Reallocation is done if the new size will exceed the capacity.; The size increases by 1.

References axom::Array< T, DIM >::m_data, and axom::Array< T, DIM >::reserveForInsert().

Referenced by axom::Array< T, DIM >::append(), axom::Array< T, DIM >::data(), and axom::Array< T, DIM >::insert().

◆ insert() [2/10]

template<typename T, int DIM = 1>

template<IndexType SFINAE = DIM, typename std::enable_if< SFINAE==1 >::type * = nullptr>

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

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

Parameters

[in]	pos	the ArrayIterator before which value will be inserted.
[in]	value	the 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/10]

template<typename T, int DIM>

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

inline

Insert elements into the array at the given position.

Parameters

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

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.

References axom::Array< T, DIM >::m_data, and axom::Array< T, DIM >::reserveForInsert().

◆ insert() [4/10]

template<typename T, int DIM = 1>

template<IndexType SFINAE = DIM, typename std::enable_if< SFINAE==1 >::type * = nullptr>

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

Insert elements into the array at the value before pos.

Parameters

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

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/10]

template<typename T, int DIM>

template<IndexType SFINAE, typename std::enable_if< SFINAE==1 >::type * >

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

inline

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

Parameters

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

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.

References axom::Array< T, DIM >::m_data, and axom::Array< T, DIM >::reserveForInsert().

◆ insert() [6/10]

template<typename T, int DIM = 1>

template<IndexType SFINAE = DIM, typename std::enable_if< SFINAE==1 >::type * = nullptr>

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

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

Parameters

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

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)

◆ append()

template<typename T, int DIM = 1>

template<typename OtherArrayType >

void axom::Array< T, DIM >::append ( const ArrayBase< T, DIM, OtherArrayType > & other )

inline

Appends an Array to the end of the calling object.

Parameters

[in] other The Array to append

Template Parameters

OtherArrayType The underlying type of the other array

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

References axom::Array< T, DIM >::emplace(), axom::Array< T, DIM >::erase(), axom::Array< T, DIM >::insert(), and axom::Array< T, DIM >::size().

◆ erase() [1/2]

template<typename T, int DIM = 1>

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

Erases an element from the Array.

Parameters

[in] pos the ArrayIterator to the element in the Array

Returns: An ArrayIterator following the last element removed.

Referenced by axom::Array< T, DIM >::append(), and axom::Array< T, DIM >::insert().

◆ erase() [2/2]

template<typename T, int DIM = 1>

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

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

Parameters

[in]	first	the ArrayIterator to the beginning of the range.
[in]	last	the ArrayIterator to end of range.

Returns: An ArrayIterator following the last element removed.

◆ emplace() [1/3]

template<typename T , int DIM>

template<typename... Args>

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

inline

Inserts new element into Array at the given position.

Parameters

[in]	pos	the position to insert element at.
[in]	args	the 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

References axom::Array< T, DIM >::m_data, and axom::Array< T, DIM >::reserveForInsert().

Referenced by axom::Array< T, DIM >::append(), and axom::Array< T, DIM >::emplace().

◆ emplace() [2/3]

template<typename T, int DIM = 1>

template<typename... Args>

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

Inserts new element into Array before pos.

Parameters

[in]	pos	the ArrayIterator to insert element before.
[in]	args	the 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.

◆ capacity()

template<typename T, int DIM = 1>

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

inline

Return the number of elements allocated for the data array.

References axom::Array< T, DIM >::m_capacity.

Referenced by axom::Array< T, DIM >::Array(), axom::sidre::Array< T, DIM >::Array(), axom::Array< T, DIM >::getAllocatorID(), and axom::Array< T, DIM >::operator=().

◆ reserve()

template<typename T, int DIM = 1>

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

inline

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

Parameters

[in] capacity the new number of elements to allocate.

References axom::Array< T, DIM >::m_capacity, and axom::Array< T, DIM >::setCapacity().

◆ begin()

template<typename T, int DIM = 1>

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

inline

Returns an ArrayIterator to the first element of the Array.

References axom::Array< T, DIM >::m_data.

Referenced by axom::Array< T, DIM >::emplace(), and axom::Array< T, DIM >::insert().

◆ end()

template<typename T, int DIM = 1>

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

inline

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

References axom::Array< T, DIM >::m_data, and axom::Array< T, DIM >::size().

Referenced by axom::Array< T, DIM >::emplace(), and axom::Array< T, DIM >::insert().

◆ shrink()

template<typename T, int DIM = 1>

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

inline

Shrink the capacity to be equal to the size.

References axom::Array< T, DIM >::m_num_elements, and axom::Array< T, DIM >::setCapacity().

◆ empty()

template<typename T, int DIM = 1>

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

inline

Returns true iff the Array stores no elements.

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

References axom::Array< T, DIM >::m_num_elements.

◆ size()

template<typename T, int DIM = 1>

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

inline

Return the number of elements stored in the data array.

References axom::Array< T, DIM >::m_num_elements, axom::Array< T, DIM >::resize(), and axom::Array< T, DIM >::swap().

Referenced by axom::Array< T, DIM >::append(), axom::Array< T, DIM >::Array(), axom::Array< T, DIM >::end(), and axom::Array< T, DIM >::operator=().

◆ resize()

template<typename T , int DIM>

template<typename... Args>

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

inline

Update the number of elements stored in the data array.

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

References axom::detail::allNonNegative(), axom::Array< T, DIM >::dynamicRealloc(), axom::Array< T, DIM >::m_capacity, axom::detail::packProduct(), and axom::Array< T, DIM >::updateNumElements().

Referenced by axom::Array< T, DIM >::size().

◆ swap()

template<typename T, int DIM>

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

inline

Exchanges the contents of this Array with the other.

References axom::Array< T, DIM >::m_capacity, axom::Array< T, DIM >::m_data, axom::Array< T, DIM >::m_num_elements, and axom::Array< T, DIM >::m_resize_ratio.

Referenced by axom::Array< T, DIM >::size().

◆ getResizeRatio()

template<typename T, int DIM = 1>

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

inline

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

References axom::Array< T, DIM >::m_resize_ratio.

◆ setResizeRatio()

template<typename T, int DIM = 1>

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

inline

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

Parameters

[in] ratio the new resize ratio.

References axom::Array< T, DIM >::m_resize_ratio.

◆ getAllocatorID()

template<typename T, int DIM = 1>

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

inline

Get the ID for the umpire allocator.

References axom::Array< T, DIM >::capacity(), axom::Array< T, DIM >::dynamicRealloc(), axom::Array< T, DIM >::initialize(), axom::Array< T, DIM >::m_allocator_id, axom::Array< T, DIM >::reserveForInsert(), axom::Array< T, DIM >::setCapacity(), and axom::Array< T, DIM >::updateNumElements().

◆ initialize()

template<typename T , int DIM>

void axom::Array< T, DIM >::initialize	(	IndexType	num_elements,
		IndexType	capacity
	)

inlineprotected

Initialize an Array instance with the given number of elements.

Parameters

[in]	num_elements	the number of elements the Array holds.
[in]	capacity	the number of elements to allocate space for.

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

References axom::Array< T, DIM >::m_capacity, axom::Array< T, DIM >::m_data, axom::Array< T, DIM >::m_num_elements, axom::Array< T, DIM >::MIN_DEFAULT_CAPACITY, axom::Array< T, DIM >::setCapacity(), and axom::Array< T, DIM >::updateNumElements().

Referenced by axom::Array< T, DIM >::Array(), axom::Array< T, DIM >::getAllocatorID(), and axom::Array< T, DIM >::operator=().

◆ reserveForInsert()

template<typename T , int DIM>

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

inlineprotected

Make space for a subsequent insertion into the array.

Parameters

[in]	n	the number of elements to insert.
[in]	pos	the 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.

References axom::Array< T, DIM >::dynamicRealloc(), axom::Array< T, DIM >::m_capacity, axom::Array< T, DIM >::m_data, axom::Array< T, DIM >::m_num_elements, and axom::Array< T, DIM >::updateNumElements().

Referenced by axom::Array< T, DIM >::emplace(), axom::Array< T, DIM >::getAllocatorID(), and axom::Array< T, DIM >::insert().

◆ updateNumElements()

template<typename T , int DIM>

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

inlineprotectedvirtual

Update the number of elements.

Parameters

[in] new_num_elements the new number of elements.

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

References axom::Array< T, DIM >::m_capacity, and axom::Array< T, DIM >::m_num_elements.

Referenced by axom::Array< T, DIM >::clear(), axom::Array< T, DIM >::getAllocatorID(), axom::Array< T, DIM >::initialize(), axom::Array< T, DIM >::insert(), axom::Array< T, DIM >::reserveForInsert(), axom::Array< T, DIM >::resize(), and axom::Array< T, DIM >::setCapacity().

◆ setCapacity()

template<typename T , int DIM>

void axom::Array< T, DIM >::setCapacity ( IndexType new_capacity )

inlineprotectedvirtual

Set the number of elements allocated for the data array.

Parameters

[in] capacity the new number of elements to allocate.

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

References axom::Array< T, DIM >::m_allocator_id, axom::Array< T, DIM >::m_capacity, axom::Array< T, DIM >::m_data, axom::Array< T, DIM >::m_num_elements, and axom::Array< T, DIM >::updateNumElements().

Referenced by axom::Array< T, DIM >::getAllocatorID(), axom::Array< T, DIM >::initialize(), axom::Array< T, DIM >::reserve(), and axom::Array< T, DIM >::shrink().

◆ dynamicRealloc()

template<typename T , int DIM>

void axom::Array< T, DIM >::dynamicRealloc ( IndexType new_num_elements )

inlineprotectedvirtual

Reallocates the data array when the size exceeds the capacity.

Parameters

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

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

References axom::ArrayBase< T, DIM, Array< T, DIM > >::blockSize(), axom::Array< T, DIM >::m_allocator_id, axom::Array< T, DIM >::m_capacity, axom::Array< T, DIM >::m_data, axom::Array< T, DIM >::m_resize_ratio, and axom::utilities::processAbort().

Referenced by axom::Array< T, DIM >::getAllocatorID(), axom::Array< T, DIM >::reserveForInsert(), and axom::Array< T, DIM >::resize().

◆ insert() [7/10]

template<typename T, int DIM = 1>

template<IndexType SFINAE, typename std::enable_if< SFINAE==1 >::type * >

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

inline

References axom::Array< T, DIM >::begin(), axom::Array< T, DIM >::end(), and axom::Array< T, DIM >::insert().

◆ insert() [8/10]

template<typename T, int DIM = 1>

template<IndexType SFINAE, typename std::enable_if< SFINAE==1 >::type * >

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

inline

References axom::Array< T, DIM >::begin(), axom::Array< T, DIM >::end(), and axom::Array< T, DIM >::insert().

◆ insert() [9/10]

template<typename T, int DIM = 1>

template<IndexType SFINAE, typename std::enable_if< SFINAE==1 >::type * >

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

inline

References axom::Array< T, DIM >::begin(), axom::Array< T, DIM >::end(), axom::Array< T, DIM >::erase(), axom::Array< T, DIM >::insert(), axom::Array< T, DIM >::m_num_elements, and axom::Array< T, DIM >::updateNumElements().

◆ emplace() [3/3]

template<typename T, int DIM = 1>

template<typename... Args>

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

inline

References axom::Array< T, DIM >::begin(), axom::Array< T, DIM >::emplace(), and axom::Array< T, DIM >::end().

◆ operator()() [1/2]

T& axom::ArrayBase< T, DIM, Array< T, DIM > >::operator() ( Args... args )

inlineinherited

Dimension-aware accessor, returns a reference to the given value.

Parameters

[in] args the parameter pack of indices in each dimension.

Note: equivalent to *(array.data() + idx).

Precondition: sizeof...(Args) == DIM; 0 <= args[i] < m_dims[i] for i in [0, DIM)

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

◆ operator()() [2/2]

const T& axom::ArrayBase< T, DIM, Array< T, DIM > >::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.

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

◆ operator[]() [1/2]

T& axom::ArrayBase< T, DIM, Array< T, DIM > >::operator[] ( 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).

Precondition: 0 <= idx < m_num_elements

◆ operator[]() [2/2]

const T& axom::ArrayBase< T, DIM, Array< T, DIM > >::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.

◆ shape()

const std::array<IndexType, DIM>& axom::ArrayBase< T, DIM, Array< T, DIM > >::shape ( ) const

inlineinherited

Returns the dimensions of the Array.

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

Referenced by axom::sidre::Array< T, DIM >::describeView().

◆ strides()

const std::array<IndexType, DIM>& axom::ArrayBase< T, DIM, Array< T, DIM > >::strides ( ) const

inlineinherited

Returns the strides of the Array.

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

◆ insert() [10/10]

void axom::ArrayBase< T, DIM, Array< T, DIM > >::insert	(	IndexType	pos,
		const ArrayBase< T, DIM, OtherArrayType > &	other
	)

inlineinherited

Appends an Array to the end of the calling object.

Parameters

[in] other The 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.

References axom::ArrayBase< T, DIM, ArrayType >::m_dims, axom::utilities::processAbort(), axom::ArrayBase< T, DIM, ArrayType >::shape(), and axom::ArrayBase< T, DIM, ArrayType >::updateStrides().

◆ blockSize()

IndexType axom::ArrayBase< T, DIM, Array< T, DIM > >::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.

Referenced by axom::sidre::Array< T, DIM >::dynamicRealloc(), and axom::Array< T, DIM >::dynamicRealloc().

◆ updateStrides()

void axom::ArrayBase< T, DIM, Array< T, DIM > >::updateStrides ( )

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.

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

Referenced by axom::sidre::Array< T, DIM >::Array().

Member Data Documentation

◆ DEFAULT_RESIZE_RATIO

template<typename T, int DIM = 1>

constexpr double axom::Array< T, DIM >::DEFAULT_RESIZE_RATIO = 2.0

static

Referenced by axom::Array< T, DIM >::Array(), and axom::Array< T, DIM >::operator=().

◆ MIN_DEFAULT_CAPACITY

template<typename T, int DIM = 1>

constexpr IndexType axom::Array< T, DIM >::MIN_DEFAULT_CAPACITY = 32

static

Referenced by axom::Array< T, DIM >::initialize().

◆ m_data

template<typename T, int DIM = 1>

T* axom::Array< T, DIM >::m_data = nullptr

protected

◆ m_num_elements

template<typename T, int DIM = 1>

IndexType axom::Array< T, DIM >::m_num_elements = 0

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.

◆ m_capacity

template<typename T, int DIM = 1>

IndexType axom::Array< T, DIM >::m_capacity = 0

protected

◆ m_resize_ratio

template<typename T, int DIM = 1>

double axom::Array< T, DIM >::m_resize_ratio = DEFAULT_RESIZE_RATIO

protected

Referenced by axom::Array< T, DIM >::Array(), axom::sidre::Array< T, DIM >::dynamicRealloc(), axom::Array< T, DIM >::dynamicRealloc(), axom::Array< T, DIM >::getResizeRatio(), axom::Array< T, DIM >::operator=(), axom::Array< T, DIM >::setResizeRatio(), and axom::Array< T, DIM >::swap().

◆ m_allocator_id

template<typename T, int DIM = 1>

int axom::Array< T, DIM >::m_allocator_id

protected

Referenced by axom::Array< T, DIM >::Array(), axom::Array< T, DIM >::dynamicRealloc(), axom::Array< T, DIM >::getAllocatorID(), axom::Array< T, DIM >::operator=(), and axom::Array< T, DIM >::setCapacity().

◆ m_dims

std::array<IndexType, DIM> axom::ArrayBase< T, DIM, Array< T, DIM > >::m_dims

protectedinherited

The sizes (extents?) in each dimension.

Referenced by axom::sidre::Array< T, DIM >::Array().

◆ m_strides

std::array<IndexType, DIM> axom::ArrayBase< T, DIM, Array< T, DIM > >::m_strides

protectedinherited

The strides in each dimension.

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

/home/docs/checkouts/readthedocs.org/user_builds/axom/checkouts/v0.6.0/src/axom/core/Array.hpp

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

template<typename T, int DIM = 1> class axom::Array< T, DIM >

Member Typedef Documentation

◆ value_type

◆ ArrayIterator

Constructor & Destructor Documentation

◆ Array() [1/5]

◆ Array() [2/5]

◆ Array() [3/5]

◆ Array() [4/5]

◆ Array() [5/5]

◆ ~Array()

Member Function Documentation

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ data() [1/2]

◆ data() [2/2]

◆ fill()

◆ set()

◆ clear()

◆ insert() [1/10]

◆ insert() [2/10]

◆ insert() [3/10]

◆ insert() [4/10]

◆ insert() [5/10]

◆ insert() [6/10]

◆ append()

◆ erase() [1/2]

◆ erase() [2/2]

◆ emplace() [1/3]

◆ emplace() [2/3]

◆ capacity()

◆ reserve()

◆ begin()

◆ end()

◆ shrink()

◆ empty()

◆ size()

◆ resize()

◆ swap()

◆ getResizeRatio()

◆ setResizeRatio()

◆ getAllocatorID()

◆ initialize()

◆ reserveForInsert()

◆ updateNumElements()

◆ setCapacity()

◆ dynamicRealloc()

◆ insert() [7/10]

◆ insert() [8/10]

◆ insert() [9/10]

◆ emplace() [3/3]

◆ operator()() [1/2]

◆ operator()() [2/2]

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ shape()

◆ strides()

◆ insert() [10/10]

◆ blockSize()

◆ updateStrides()

Member Data Documentation

◆ DEFAULT_RESIZE_RATIO

◆ MIN_DEFAULT_CAPACITY

◆ m_data

◆ m_num_elements

◆ m_capacity

◆ m_resize_ratio

◆ m_allocator_id

◆ m_dims

◆ m_strides

template<typename T, int DIM = 1>
class axom::Array< T, DIM >