Provides a generic multi-component array container. More...

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

Inheritance diagram for axom::Array< T >:

Public Member Functions
virtual	~Array ()

Native Storage Array Constructors
	Array (IndexType num_tuples, IndexType num_components=1, IndexType capacity=0)
	Constructs an Array instance with the given number of tuples. More...

External Storage Array Constructors
	Array (T *data, IndexType num_tuples, IndexType num_components=1, IndexType capacity=0)
	Constructs an Array instance with the given number of tuples from an external data buffer. More...

Array tuple access operators
T &	operator() (IndexType pos, IndexType component=0)
	Accessor, returns a reference to the given component of the specified tuple. More...

const T &	operator() (IndexType pos, IndexType component=0) const


T &	operator[] (IndexType idx)
	Accessor, returns a reference to the given value. More...

const T &	operator[] (IndexType idx) const


T *	getData ()
	Return a pointer to the array of data. More...

const T *	getData () const

Array methods to modify the data.
void	fill (const T &value)
	Set all the values of the array. More...

void	append (const T &value)
	Append a value to the end of the array. More...

void	append (const T *tuples, IndexType n)
	Append tuples to the end of the array. More...

void	set (const T *tuples, IndexType n, IndexType pos)
	Modify the values of existing tuples. More...

void	insert (const T &value, IndexType pos)
	Insert a tuple into the array at the given position. More...

void	insert (const T *tuples, IndexType n, IndexType pos)
	Insert tuples into the array at the given position. More...

void	emplace (IndexType n, IndexType pos, const T &value=T())
	Insert multiple copies of the same value at the given position. More...

Array methods to query and set attributes
IndexType	capacity () const
	Return the number of tuples 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...

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 tuples stored in the data array. More...

void	resize (IndexType new_num_tuples)
	Update the number of tuples stored in the data array. 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...

IndexType	numComponents () const
	Return the number of components per tuple. More...

bool	isExternal () const
	Return true iff the external buffer constructor was called. More...

virtual bool	isInSidre () const
	Return true iff a sidre constructor was called. More...

Static Public Attributes
static constexpr double	DEFAULT_RESIZE_RATIO = 2.0

static constexpr IndexType	MIN_DEFAULT_CAPACITY = 32

Protected Member Functions
	Array ()
	Default constructor supports infrastructure in subclasses. More...

void	initialize (IndexType num_tuples, IndexType num_components, IndexType capacity)
	Initialize an Array instance with the given number of tuples. More...

T *	reserveForInsert (IndexType n, IndexType pos)
	Make space for a subsequent insertion into the array. More...

virtual void	updateNumTuples (IndexType new_num_tuples)
	Update the number of tuples. More...

virtual void	setCapacity (IndexType new_capacity)
	Set the number of tuples allocated for the data array. More...

virtual void	dynamicRealloc (IndexType new_num_tuples)
	Reallocates the data array when the size exceeds the capacity. More...

	Array (const Array &)=delete

Array &	operator= (const Array &)=delete

	Array (const Array &&)=delete

Array &	operator= (const Array &&)=delete

Internal bounds-checking routines
bool	inBounds (IndexType pos, IndexType component) const
	Test if pos and component are within bounds. More...

bool	inBounds (IndexType idx) const
	Test if idx is within bounds. More...

Protected Attributes
T *	m_data

IndexType	m_num_tuples

IndexType	m_capacity

IndexType	m_num_components

double	m_resize_ratio

bool const	m_is_external

Detailed Description

template<typename T>
class axom::Array< T >

Provides a generic multi-component array container.

The Array class provides a generic multi-component array container with dynamic re-allocation and insertion. Each element in the array is a tuple consisting of 1 or more components, which are stored contiguously.

Depending on which constructor is used, the Array object can have two different underlying storage types:

Native Storage

When using native storage, the Array object manages all memory. Typically, the Array object will allocate extra space to facilitate the insertion of new elements and minimize the number of reallocations. The actual capacity of the array (i.e., total number of tuples that the Array can hold) can be queried by calling the capacity() function. When allocated memory is used up, inserting a new element triggers a re-allocation. At each re-allocation, extra space is allocated according to the resize_ratio parameter, which is set to 2.0 by default. To return all extra memory, an application can call shrink().

Note
The Array destructor deallocates and returns all memory associated with it to the system.
External Storage

An Array object may be constructed from an external, user-supplied buffer consisting of the given number of tuples and specified number of components per tuple. In this case, the Array object does not own the memory. Instead, the Array object makes a shallow copy of the pointer.

Warning
An Array object that points to an external buffer has a fixed size and cannot be dynamically resized.

Note
The Array destructor does not deallocate a user-supplied buffer, since it does not manage that memory.

Warning
Reallocations tend to be costly operations in terms of performance. Use reserve() when the number of nodes is known a priori, or opt to use a constructor that takes an actual size and capacity when possible.

Template Parameters

T the type of the values to hold.

Constructor & Destructor Documentation

◆ Array() [1/5]

template<typename T >

axom::Array< T >::Array	(	IndexType	num_tuples,
		IndexType	num_components = `1`,
		IndexType	capacity = `0`
	)

Constructs an Array instance with the given number of tuples.

Parameters

[in]	num_tuples	the number of tuples the Array holds.
[in]	num_components	the number of values per tuple. If not specified defaults to 1.
[in]	capacity	the number of tuples to allocate space for.

Note: If no capacity or capacity less than num_tuples is specified then it will default to at least num_tuples * DEFAULT_RESIZE_RATIO.; a capacity is specified for the number of tuples to store in the array and does not correspond to the actual bytesize.

Precondition: num_tuples >= 0; num_components >= 1

Postcondition: capacity() >= size(); size() == num_tuples; numComponents() == num_components; getResizeRatio() == DEFAULT_RESIZE_RATIO

◆ Array() [2/5]

template<typename T>

axom::Array< T >::Array	(	T *	data,
		IndexType	num_tuples,
		IndexType	num_components = `1`,
		IndexType	capacity = `0`
	)

Constructs an Array instance with the given number of tuples from an external data buffer.

Parameters

[in]	data	the external data this Array will wrap.
[in]	num_tuples	the number of tuples in the Array.
[in]	num_components	the number of values per tuple. If not specified defaults to 1.
[in]	capacity	the capacity of the external buffer.

Precondition: data != nullptr; num_tuples > 0; num_components >= 1

Postcondition: numComponents() == num_components; getResizeRatio == 0.0

Note: a capacity is specified for the number of tuples to store in the array and does not correspond to the actual bytesize.; If no capacity or capacity less than num_tuples is specified then it will default to the number of tuples.; This constructor wraps the supplied buffer and does not own the data. Consequently, the Array instance cannot be reallocated.

◆ ~Array()

template<typename T >

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

virtual

Destructor. Frees the associated buffer unless the memory is external.

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

◆ Array() [3/5]

template<typename T>

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

protected

Default constructor supports infrastructure in subclasses.

◆ Array() [4/5]

template<typename T>

axom::Array< T >::Array ( const Array< T > & )

protecteddelete

◆ Array() [5/5]

template<typename T>

axom::Array< T >::Array ( const Array< T > && )

protecteddelete

Member Function Documentation

◆ operator()() [1/2]

template<typename T>

T& axom::Array< T >::operator()	(	IndexType	pos,
		IndexType	component = `0`
	)

inline

Accessor, returns a reference to the given component of the specified tuple.

Parameters

[in]	pos	the tuple to query.
[in]	component	the component to return.

Precondition: 0 <= pos < size(); 0 <= component < numComponents()

◆ operator()() [2/2]

template<typename T>

const T& axom::Array< T >::operator()	(	IndexType	pos,
		IndexType	component = `0`
	)		const

inline

◆ operator[]() [1/2]

template<typename T>

T& axom::Array< T >::operator[] ( IndexType idx )

inline

Accessor, returns a reference to the given value.

Parameters

[in] idx the position of the value to return.

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

Precondition: 0 <= idx < m_num_tuples * m_num_components

◆ operator[]() [2/2]

template<typename T>

const T& axom::Array< T >::operator[] ( IndexType idx ) const

inline

◆ getData() [1/2]

template<typename T>

T* axom::Array< T >::getData ( )

inline

Return a pointer to the array of data.

Referenced by axom::mint::ConnectivityArray< TYPE >::getValuePtr(), and axom::mint::ConnectivityArray< TYPE >::operator[]().

◆ getData() [2/2]

template<typename T>

const T* axom::Array< T >::getData ( ) const

inline

◆ fill()

template<typename T>

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

inline

Set all the values of the array.

Parameters

[in] value the value to set to.

◆ append() [1/2]

template<typename T>

void axom::Array< T >::append ( const T & value )

inline

Append a value to the end of the array.

Parameters

[in] value the value to append.

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

Precondition: m_num_components == 1.

Referenced by axom::mint::ConnectivityArray< TYPE >::appendM().

◆ append() [2/2]

template<typename T>

void axom::Array< T >::append	(	const T *	tuples,
		IndexType	n
	)

inline

Append tuples to the end of the array.

Parameters

[in]	tuples	the tuples to append.
[in]	n	the number of tuples to append.

Note: It's assumed that tuples is of length n * m_num_components.; Reallocation is done if the new size will exceed the capacity.

◆ set()

template<typename T>

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

inline

Modify the values of existing tuples.

Parameters

[in]	tuples	the new tuples to write.
[in]	n	the number of tuples to write.
[in]	pos	the position at which to begin writing.

Note: It's assumed that tuples is of length n * m_num_components.; The size is unchanged by calls to set.

Precondition: pos + n <= m_num_tuples.

Referenced by axom::mint::ConnectivityArray< TYPE >::set(), and axom::mint::ConnectivityArray< TYPE >::setM().

◆ insert() [1/2]

template<typename T>

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

inline

Insert a tuple into the array at the given position.

Parameters

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

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

Precondition: numComponents() == 1.

Referenced by axom::mint::ConnectivityArray< TYPE >::insertM().

◆ insert() [2/2]

template<typename T>

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

inline

Insert tuples into the array at the given position.

Parameters

[in]	tuples	the tuples to insert.
[in]	n	the number of tuples to insert.
[in]	pos	the position at which to begin the insertion.

Note: It's assumed that tuples is of length n * m_num_components.; Reallocation is done if the new size will exceed the capacity.; The size increases by n.

Precondition: pos <= m_num_tuples.

◆ emplace()

template<typename T>

void axom::Array< T >::emplace	(	IndexType	n,
		IndexType	pos,
		const T &	value = `T()`
	)

inline

Insert multiple copies of the same value at the given position.

Parameters

[in]	n	the number of tuples to insert.
[in]	pos	the position to insert at.
[in]	value	the value for each component of the new tuples. If not specified defaults to the default value of T (zero for most numeric types).

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 tuples in the middle of the array.

Precondition: pos <= m_num_tuples.

◆ capacity()

template<typename T>

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

inline

Return the number of tuples allocated for the data array.

Referenced by axom::mint::ConnectivityArray< TYPE >::getIDCapacity(), and axom::mint::ConnectivityArray< TYPE >::reserve().

◆ reserve()

template<typename T>

void axom::Array< T >::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 tuples to allocate.

Referenced by axom::mint::ConnectivityArray< TYPE >::reserve().

◆ shrink()

template<typename T>

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

inline

Shrink the capacity to be equal to the size.

Referenced by axom::mint::ConnectivityArray< TYPE >::shrink().

◆ empty()

template<typename T>

bool axom::Array< T >::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.

Referenced by axom::mint::ConnectivityArray< TYPE >::empty().

◆ size()

template<typename T>

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

inline

Return the number of tuples stored in the data array.

Referenced by axom::mint::ConnectivityArray< TYPE >::getNumberOfIDs(), and axom::mint::ConnectivityArray< TYPE >::getNumberOfValues().

◆ resize()

template<typename T >

void axom::Array< T >::resize ( IndexType new_num_tuples )

inline

Update the number of tuples stored in the data array.

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

Referenced by axom::mint::ConnectivityArray< TYPE >::resize().

◆ getResizeRatio()

template<typename T>

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

inline

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

Referenced by axom::mint::ConnectivityArray< TYPE >::getResizeRatio().

◆ setResizeRatio()

template<typename T>

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

inline

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

Parameters

[in] ratio the new resize ratio.

Referenced by axom::mint::ConnectivityArray< TYPE >::setResizeRatio().

◆ numComponents()

template<typename T>

IndexType axom::Array< T >::numComponents ( ) const

inline

Return the number of components per tuple.

Referenced by axom::mint::ConnectivityArray< TYPE >::ConnectivityArray().

◆ isExternal()

template<typename T>

bool axom::Array< T >::isExternal ( ) const

inline

Return true iff the external buffer constructor was called.

Referenced by axom::mint::RectilinearMesh::isExternal(), and axom::mint::ConnectivityArray< TYPE >::isExternal().

◆ isInSidre()

template<typename T>

virtual bool axom::Array< T >::isInSidre ( ) const

inlinevirtual

Return true iff a sidre constructor was called.

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

Referenced by axom::mint::ConnectivityArray< TYPE >::isInSidre().

◆ initialize()

template<typename T >

void axom::Array< T >::initialize	(	IndexType	num_tuples,
		IndexType	num_components,
		IndexType	capacity
	)

inlineprotected

Initialize an Array instance with the given number of tuples.

Parameters

[in]	num_tuples	the number of tuples the Array holds.
[in]	num_components	the number of values per tuple. If not specified defaults to 1.
[in]	capacity	the number of tuples to allocate space for.

Note: If no capacity or capacity less than num_tuples is specified then it will default to at least num_tuples * DEFAULT_RESIZE_RATIO.; a capacity is specified for the number of tuples to store in the array and does not correspond to the actual bytesize.

Precondition: num_tuples >= 0; num_components >= 1

Postcondition: capacity() >= size(); size() == num_tuples; numComponents() == num_components; getResizeRatio() == DEFAULT_RESIZE_RATIO

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

◆ reserveForInsert()

template<typename T >

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

inlineprotected

Make space for a subsequent insertion into the array.

Parameters

[in]	n	the number of tuples 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.

◆ updateNumTuples()

template<typename T >

void axom::Array< T >::updateNumTuples ( IndexType new_num_tuples )

inlineprotectedvirtual

Update the number of tuples.

Parameters

[in] new_num_tuples the new number of tuples.

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

◆ setCapacity()

template<typename T >

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

inlineprotectedvirtual

Set the number of tuples allocated for the data array.

Parameters

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

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

◆ dynamicRealloc()

template<typename T >

void axom::Array< T >::dynamicRealloc ( IndexType new_num_tuples )

inlineprotectedvirtual

Reallocates the data array when the size exceeds the capacity.

Parameters

[in] new_num_tuples the number of tuples which exceeds the current capacity.

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

◆ inBounds() [1/2]

template<typename T>

bool axom::Array< T >::inBounds	(	IndexType	pos,
		IndexType	component
	)		const

inlineprotected

Test if pos and component are within bounds.

◆ inBounds() [2/2]

template<typename T>

bool axom::Array< T >::inBounds ( IndexType idx ) const

inlineprotected

Test if idx is within bounds.

◆ operator=() [1/2]

template<typename T>

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

protecteddelete

◆ operator=() [2/2]

template<typename T>

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

protecteddelete

Member Data Documentation

◆ DEFAULT_RESIZE_RATIO

template<typename T>

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

static

◆ MIN_DEFAULT_CAPACITY

template<typename T>

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

static

◆ m_data

template<typename T>

T* axom::Array< T >::m_data

protected

Referenced by axom::sidre::Array< T >::Array(), axom::sidre::Array< T >::reallocViewData(), and axom::sidre::Array< T >::~Array().

◆ m_num_tuples

template<typename T>

IndexType axom::Array< T >::m_num_tuples

protected

Referenced by axom::sidre::Array< T >::Array(), axom::sidre::Array< T >::describeView(), axom::sidre::Array< T >::setCapacity(), and axom::sidre::Array< T >::updateNumTuples().

◆ m_capacity

template<typename T>

IndexType axom::Array< T >::m_capacity

protected

Referenced by axom::sidre::Array< T >::Array(), axom::sidre::Array< T >::reallocViewData(), and axom::sidre::Array< T >::updateNumTuples().

◆ m_num_components

template<typename T>

IndexType axom::Array< T >::m_num_components

protected

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

◆ m_resize_ratio

template<typename T>

double axom::Array< T >::m_resize_ratio

protected

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

◆ m_is_external

template<typename T>

bool const axom::Array< T >::m_is_external

protected

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

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

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

template<typename T> class axom::Array< T >

Constructor & Destructor Documentation

◆ Array() [1/5]

◆ Array() [2/5]

◆ ~Array()

◆ Array() [3/5]

◆ Array() [4/5]

◆ Array() [5/5]

Member Function Documentation

◆ operator()() [1/2]

◆ operator()() [2/2]

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ getData() [1/2]

◆ getData() [2/2]

◆ fill()

◆ append() [1/2]

◆ append() [2/2]

◆ set()

◆ insert() [1/2]

◆ insert() [2/2]

◆ emplace()

◆ capacity()

◆ reserve()

◆ shrink()

◆ empty()

◆ size()

◆ resize()

◆ getResizeRatio()

◆ setResizeRatio()

◆ numComponents()

◆ isExternal()

◆ isInSidre()

◆ initialize()

◆ reserveForInsert()

◆ updateNumTuples()

◆ setCapacity()

◆ dynamicRealloc()

◆ inBounds() [1/2]

◆ inBounds() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

Member Data Documentation

◆ DEFAULT_RESIZE_RATIO

◆ MIN_DEFAULT_CAPACITY

◆ m_data

◆ m_num_tuples

◆ m_capacity

◆ m_num_components

◆ m_resize_ratio

◆ m_is_external

template<typename T>
class axom::Array< T >