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

Provides a generic multi-component array, contained in Sidre. More...

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

Inheritance diagram for axom::sidre::Array< T >:

Public Member Functions

 Array ()=delete
 Default constructor. Disabled. More...
 
virtual ~Array ()
 
Sidre Array constructors
 Array (View *view)
 Creates an Array instance from a View that already has data. More...
 
 Array (View *view, axom::IndexType num_tuples, axom::IndexType num_components=1, axom::IndexType capacity=0)
 Creates an Array instance of num_tuples size, where each tuple consists of num_components values and populates the associated View. More...
 
Array methods to query and set attributes
virtual 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...
 
const ViewgetView () const
 Return a pointer to the View that this Array wraps. 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...
 

Static Public Attributes

static constexpr double DEFAULT_RESIZE_RATIO = 2.0
 
static constexpr IndexType MIN_DEFAULT_CAPACITY = 32
 

Protected Member Functions

virtual void updateNumTuples (axom::IndexType new_num_tuples)
 Update the number of tuples. More...
 
virtual void setCapacity (axom::IndexType new_capacity)
 Set the number of tuples allocated for the data array. More...
 
virtual void dynamicRealloc (axom::IndexType new_num_tuples)
 Reallocates the data array when the size exceeds the capacity. More...
 
void describeView ()
 Applies this Array's type and dimensions to the sidre View. More...
 
axom::IndexType getViewShape (int dim) const
 Given a non-empty View of dimension 2, returns the length of the given dimension. More...
 
void reallocViewData (IndexType new_capacity)
 Allocates space within the Array's View. More...
 
 DISABLE_COPY_AND_ASSIGNMENT (Array)
 
 DISABLE_MOVE_AND_ASSIGNMENT (Array)
 
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...
 
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...
 

Static Protected Member Functions

template<typename U = T>
static constexpr std::enable_if<!std::is_enum< U >::value, TypeID >::type sidreTypeId ()
 Return the TypeID corresponding to T. This function handles when T is not an enum. More...
 
template<typename U = T>
static constexpr std::enable_if< std::is_enum< U >::value, TypeID >::type sidreTypeId ()
 Return the TypeID corresponding to T. This function handles when T is an enum. More...
 

Protected Attributes

Viewm_view
 
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::sidre::Array< T >

Provides a generic multi-component array, contained in Sidre.

This sidre::Array class extends axom::utilities::Array by storing data in a Sidre DataStore. This 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.

Objects of the sidre::Array class may be constructed from a View. All array operations can be performed as with the base axom::utilities::Array class. The size of the Array can grow as needed, and all memory management is delegated to Sidre.

Note
When the Array object is deleted, it does not delete the associated data in Sidre, since, Sidre owns the data.
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
Tthe type of the values to hold.
See also
Group
View

Constructor & Destructor Documentation

◆ Array() [1/3]

template<typename T>
axom::sidre::Array< T >::Array ( )
delete

Default constructor. Disabled.

◆ Array() [2/3]

template<typename T >
axom::sidre::Array< T >::Array ( View view)

Creates an Array instance from a View that already has data.

Parameters
[in]viewthe View that holds this Array's data.
Note
The Sidre view shape has two dimensions. The first dimension corresponds to the max capacity of the array and the second corresponds to the number of components per tuple.
Precondition
view != nullptr
view->isEmpty() == false.
view->getNumDimensions() == 2
Postcondition
capacity() == view->getDimension(0)
numComponents() == view->getDimension(1)
getResizeRatio() == DEFAULT_RESIZE_RATIO

References axom::sidre::View::getBuffer(), axom::sidre::Buffer::getNumElements(), axom::sidre::View::getTypeID(), axom::sidre::Array< T >::getViewShape(), axom::sidre::View::getVoidPtr(), axom::sidre::View::isEmpty(), axom::Array< T >::m_capacity, axom::Array< T >::m_data, axom::Array< T >::m_num_components, axom::Array< T >::m_num_tuples, axom::sidre::Array< T >::m_view, axom::sidre::Array< T >::sidreTypeId(), and SLIC_ERROR_IF.

◆ Array() [3/3]

template<typename T >
axom::sidre::Array< T >::Array ( View view,
axom::IndexType  num_tuples,
axom::IndexType  num_components = 1,
axom::IndexType  capacity = 0 
)

Creates an Array instance of num_tuples size, where each tuple consists of num_components values and populates the associated View.

Parameters
[in]viewthe View that will hold this Array's data.
[in]num_tuplesthe number of tuples accounted for in the Array.
[in]num_componentsthe number of values per tuple. If not specified defaults to 1.
[in]capacitythe number of tuples to allocate space for.
Note
The last argument is optional. If not specified or if less than num_tuples, the capacity of the array will be initialized to num_tuples * DEFAULT_RESIZE_RATIO.
The view is expected to be empty and will be populated to hold this Array's data.
The Sidre view shape has two dimensions. The first dimension corresponds to the number of tuples and the second corresponds to the number of components per tuple.
Precondition
view != nullptr
view->isEmpty() == true
num_tuples >= 1
num_components >= 1
Postcondition
view->getNumDimensions() == 2
view->isEmpty() == false
size() == num_tuples.
numComponents() == num_components
getResizeRatio() == DEFAULT_RESIZE_RATIO

References axom::Array< T >::initialize(), axom::sidre::View::isEmpty(), axom::Array< T >::m_capacity, axom::Array< T >::m_data, axom::Array< T >::m_num_components, axom::Array< T >::m_num_tuples, axom::sidre::Array< T >::m_view, SLIC_ASSERT, and SLIC_ERROR_IF.

◆ ~Array()

template<typename T >
axom::sidre::Array< T >::~Array ( )
virtual

Destructor. Frees the associated buffer unless owned by Sidre.

Reimplemented from axom::Array< T >.

References axom::Array< T >::m_data, and axom::sidre::Array< T >::m_view.

Member Function Documentation

◆ isExternal()

template<typename T>
virtual bool axom::sidre::Array< T >::isExternal ( ) const
inlinevirtual

Return true iff the external buffer constructor was called.

◆ isInSidre()

template<typename T>
virtual bool axom::sidre::Array< T >::isInSidre ( ) const
inlinevirtual

Return true iff a sidre constructor was called.

Reimplemented from axom::Array< T >.

◆ getView()

template<typename T>
const View* axom::sidre::Array< T >::getView ( ) const
inline

Return a pointer to the View that this Array wraps.

◆ updateNumTuples()

template<typename T >
void axom::sidre::Array< T >::updateNumTuples ( axom::IndexType  new_num_tuples)
inlineprotectedvirtual

Update the number of tuples.

Parameters
[in]new_num_tuplesthe new number of tuples.

Reimplemented from axom::Array< T >.

References axom::sidre::Array< T >::describeView(), axom::Array< T >::m_capacity, axom::Array< T >::m_num_tuples, and SLIC_ASSERT.

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

◆ setCapacity()

template<typename T >
void axom::sidre::Array< T >::setCapacity ( axom::IndexType  new_capacity)
inlineprotectedvirtual

Set the number of tuples allocated for the data array.

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

Reimplemented from axom::Array< T >.

References axom::Array< T >::m_num_tuples, axom::sidre::Array< T >::reallocViewData(), SLIC_ASSERT, and axom::sidre::Array< T >::updateNumTuples().

◆ dynamicRealloc()

template<typename T >
void axom::sidre::Array< T >::dynamicRealloc ( axom::IndexType  new_num_tuples)
inlineprotectedvirtual

Reallocates the data array when the size exceeds the capacity.

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

Reimplemented from axom::Array< T >.

References axom::Array< T >::m_resize_ratio, axom::sidre::Array< T >::reallocViewData(), and SLIC_ERROR_IF.

◆ sidreTypeId() [1/2]

template<typename T>
template<typename U = T>
static constexpr std::enable_if<!std::is_enum<U>::value, TypeID>::type axom::sidre::Array< T >::sidreTypeId ( )
inlinestaticprotected

Return the TypeID corresponding to T. This function handles when T is not an enum.

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

◆ sidreTypeId() [2/2]

template<typename T>
template<typename U = T>
static constexpr std::enable_if<std::is_enum<U>::value, TypeID>::type axom::sidre::Array< T >::sidreTypeId ( )
inlinestaticprotected

Return the TypeID corresponding to T. This function handles when T is an enum.

◆ describeView()

template<typename T >
void axom::sidre::Array< T >::describeView ( )
inlineprotected

◆ getViewShape()

template<typename T >
axom::IndexType axom::sidre::Array< T >::getViewShape ( int  dim) const
inlineprotected

Given a non-empty View of dimension 2, returns the length of the given dimension.

Parameters
[in]viewthe View to examine.
[in]dimthe dimension (0 or 1) to return the length of.
Precondition
0 <= dim <= 1

References axom::sidre::View::getNumDimensions(), axom::sidre::View::getShape(), axom::sidre::View::isEmpty(), axom::sidre::Array< T >::m_view, and SLIC_ERROR_IF.

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

◆ reallocViewData()

◆ DISABLE_COPY_AND_ASSIGNMENT()

template<typename T>
axom::sidre::Array< T >::DISABLE_COPY_AND_ASSIGNMENT ( Array< T >  )
protected

◆ DISABLE_MOVE_AND_ASSIGNMENT()

template<typename T>
axom::sidre::Array< T >::DISABLE_MOVE_AND_ASSIGNMENT ( Array< T >  )
protected

◆ operator()() [1/2]

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

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

Parameters
[in]posthe tuple to query.
[in]componentthe 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
inlineinherited

◆ operator[]() [1/2]

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

Accessor, returns a reference to the given value.

Parameters
[in]idxthe 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
inlineinherited

◆ getData() [1/2]

template<typename T>
T* axom::Array< T >::getData ( )
inlineinherited

◆ getData() [2/2]

template<typename T>
const T* axom::Array< T >::getData ( ) const
inlineinherited

◆ fill()

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

Set all the values of the array.

Parameters
[in]valuethe value to set to.

◆ append() [1/2]

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

Append a value to the end of the array.

Parameters
[in]valuethe 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 
)
inlineinherited

Append tuples to the end of the array.

Parameters
[in]tuplesthe tuples to append.
[in]nthe 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 
)
inlineinherited

Modify the values of existing tuples.

Parameters
[in]tuplesthe new tuples to write.
[in]nthe number of tuples to write.
[in]posthe 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 
)
inlineinherited

Insert a tuple into the array at the given position.

Parameters
[in]valuethe value to insert.
[in]posthe 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 
)
inlineinherited

Insert tuples into the array at the given position.

Parameters
[in]tuplesthe tuples to insert.
[in]nthe number of tuples to insert.
[in]posthe 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() 
)
inlineinherited

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

Parameters
[in]nthe number of tuples to insert.
[in]posthe position to insert at.
[in]valuethe 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
inlineinherited

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

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

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

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

◆ shrink()

template<typename T>
void axom::Array< T >::shrink ( )
inlineinherited

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
inlineinherited

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
inlineinherited

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

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
inlineinherited

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

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

Parameters
[in]ratiothe new resize ratio.

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

◆ numComponents()

template<typename T>
IndexType axom::Array< T >::numComponents ( ) const
inlineinherited

Return the number of components per tuple.

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

◆ initialize()

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

Initialize an Array instance with the given number of tuples.

Parameters
[in]num_tuplesthe number of tuples the Array holds.
[in]num_componentsthe number of values per tuple. If not specified defaults to 1.
[in]capacitythe 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 
)
inlineprotectedinherited

Make space for a subsequent insertion into the array.

Parameters
[in]nthe number of tuples 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.

◆ inBounds() [1/2]

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

Test if pos and component are within bounds.

◆ inBounds() [2/2]

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

Test if idx is within bounds.

Member Data Documentation

◆ m_view

◆ DEFAULT_RESIZE_RATIO

template<typename T>
constexpr double axom::Array< T >::DEFAULT_RESIZE_RATIO = 2.0
staticinherited

◆ MIN_DEFAULT_CAPACITY

template<typename T>
constexpr IndexType axom::Array< T >::MIN_DEFAULT_CAPACITY = 32
staticinherited

◆ m_data

template<typename T>
T* axom::Array< T >::m_data
protectedinherited

◆ m_num_tuples

◆ m_capacity

◆ m_num_components

template<typename T>
IndexType axom::Array< T >::m_num_components
protectedinherited

◆ m_resize_ratio

template<typename T>
double axom::Array< T >::m_resize_ratio
protectedinherited

◆ m_is_external

template<typename T>
bool const axom::Array< T >::m_is_external
protectedinherited

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