#include <Array2D.h>

Classes
struct	TableEntry

Public Member Functions
	Array2D ()=default

	Array2D (size_t numRows, size_t numPreAllocatedElemsPerRow=2)

void	Resize (size_t numRows, bool autoShrink=false)

void	Add (size_t rowIndex, const T &element)

void	Remove (size_t rowIndex, size_t elementIndex)

void	RemoveRow (size_t rowIndex, bool autoShrink=false)

void	RemoveRows (size_t startRow, size_t endRow, bool autoShrink=false)

void	Shrink ()

void	SetNumPreCachedElements (size_t numElemsPerRow)

size_t	GetNumPreCachedElements () const

size_t	GetNumElements (size_t rowIndex) const

T *	GetElements (size_t rowIndex)

T &	GetElement (size_t rowIndex, size_t elementNr)

const T &	GetElement (size_t rowIndex, size_t elementNr) const

void	SetElement (size_t rowIndex, size_t elementNr, const T &value)

size_t	GetNumRows () const

float	CalcUsedElementMemoryPercentage () const

void	Swap (size_t rowA, size_t rowB)

size_t	CalcTotalNumElements () const

void	Clear (bool freeMem=true)

void	LogContents ()

AZStd::vector< TableEntry > &	GetIndexTable ()

AZStd::vector< T > &	GetData ()

Detailed Description

template<class T>
class MCore::Array2D< T >

A dynamic 2D array template. This would be a better solution than "Array< Array< T > >", because the Array inside Array will perform many allocations, while this specialized 2D array will only perform two similar allocations. What it does is keep one big array of data elements, and maintain a table that indices inside this big array. We advise you to call the Shrink function after you performed a number of operations on the array, to maximize its memory usage efficiency.

The layout of the array is as following:


[ROW0]: [E0][E1][E2]
[ROW1]: [E0][E1]
[ROW2]: [E0][E1][E2][E3]
[ROW3]: [E0]

Where E0, E1, E2, etc are elements of the specified type T. Each row can have a different amount of elements that can be added or removed dynamically. Also rows can be deleted or added when desired.

Constructor & Destructor Documentation

◆ Array2D() [1/2]

template<class T >

MCore::Array2D< T >::Array2D ( )

default

The default constructor. The number of pre-cached/allocated elements per row is set to a value of 2 on default. You can use the SetNumPreCachedElements(...) method to adjust this value. Make sure you adjust this value before you call the Resize method though, otherwise it will have no immediate effect.

◆ Array2D() [2/2]

template<class T >

MCore::Array2D< T >::Array2D	(	size_t	numRows,
		size_t	numPreAllocatedElemsPerRow = `2`
	)

inline

Extended constructor which will automatically initialize the array dimensions. Basically this will initialize the array dimensions at (numRows x numPreAllocatedElemsPerRow) elements. Please note though, that this will NOT add actual elements. So you can't get values from the elements yet. This would just pre-allocate data. You have to use the Add method to actually fill the items.

Parameters

numRows	The number of rows the array should have.
numPreAllocatedElemsPerRow	The number of pre-cached/allocated elements per row.

Member Function Documentation

◆ Add()

template<class T >

void Array2D::Add	(	size_t	rowIndex,
		const T &	element
	)

Add an element to the list of elements in a given row.

Parameters

rowIndex	The row number to add the element to.
element	The value of the element to add.

◆ CalcTotalNumElements()

template<class T >

size_t Array2D::CalcTotalNumElements ( ) const

Calculate the total number of used elements. A used element is an element that has been added and that has a valid value stored. This excludes pre-allocated/cached elements.

Returns: The total number of elements stored in the array.

◆ CalcUsedElementMemoryPercentage()

template<class T >

float MCore::Array2D< T >::CalcUsedElementMemoryPercentage ( ) const

inline

Calculate the percentage of memory that is filled with element data. When this is 100%, then all allocated element data is filled and used. When it would be 25% then only 25% of all allocated element data is used. This is an indication that you should most likely use the Shrink method, which will ensure that the memory usage will become 100% again, which would be most optimal.

Returns: The percentage (in range of 0..100) of used element memory.

◆ Clear()

template<class T >

void MCore::Array2D< T >::Clear ( bool freeMem = true )

inline

Clear all contents. This deletes all rows and clears all their their elements as well. Please keep in mind though, that when you have an array of pointers to objects you allocated, that you still have to delete those objects by hand! The Clear function will not delete those.

Parameters

freeMem When set to true, all memory used by the array internally will be deleted. If set to false, the memory will not be deleted and can be reused later on again without doing any memory realloc when possible.

◆ GetData()

template<class T >

AZStd::vector< T > & MCore::Array2D< T >::GetData ( )

inline

Get the data array. This contains the data array in which the index table points. Normally you shouldn't be using this method. However it is useful in some specific cases.

Returns: The data array that contains all elements.

◆ GetElement() [1/2]

template<class T >

T & MCore::Array2D< T >::GetElement	(	size_t	rowIndex,
		size_t	elementNr
	)

inline

Get the data of a given element.

Parameters

rowIndex	The row number where the element is stored.
elementNr	The element number inside this row to retrieve.

Returns: A reference to the element data.

◆ GetElement() [2/2]

template<class T >

const T & MCore::Array2D< T >::GetElement	(	size_t	rowIndex,
		size_t	elementNr
	)		const

inline

Get the data of a given element.

Parameters

rowIndex	The row number where the element is stored.
elementNr	The element number inside this row to retrieve.

Returns: A const reference to the element data.

◆ GetElements()

template<class T >

T * MCore::Array2D< T >::GetElements ( size_t rowIndex )

inline

Get a pointer to the element data stored in a given row. Use this method with care as it can easily overwrite data from other elements. All element data for a given row is stored sequential, so right after eachother in one continuous piece of memory. The next row's element data however might not be connected to the memory of row before that! Also only use this method when the GetNumElements(...) method for this row returns a value greater than zero.

Parameters

rowIndex the row number.

Returns: A pointer to the element data for the given row.

◆ GetIndexTable()

template<class T >

AZStd::vector< TableEntry > & MCore::Array2D< T >::GetIndexTable ( )

inline

Get the index table. This table describes for each row the start index and number of elements for the row. The length of the array equals the value returned by GetNumRows().

Returns: The array of index table entries, which specify the start indices and number of entries per row.

◆ GetNumElements()

template<class T >

size_t MCore::Array2D< T >::GetNumElements ( size_t rowIndex ) const

inline

Get the number of stored elements inside a given row.

Parameters

rowIndex The row number.

Returns: The number of elements stored inside this row.

◆ GetNumPreCachedElements()

template<class T >

size_t MCore::Array2D< T >::GetNumPreCachedElements ( ) const

inline

Get the number of pre-cached/allocated elements per row, when creating new rows. See the SetNumPreCachedElements for more information.

Returns: The number of elements per row that will be pre-allocated/cached when adding a new row.

See also: SetNumPreCachedElements.

◆ GetNumRows()

template<class T >

size_t MCore::Array2D< T >::GetNumRows ( ) const

inline

Get the number of rows in the 2D array.

Returns: The number of rows.

◆ LogContents()

template<class T >

void MCore::Array2D< T >::LogContents ( )

Log all array contents. This will log the number of rows, number of elements, used element memory percentage, as well as some details about each row.

◆ Remove()

template<class T >

void Array2D::Remove	(	size_t	rowIndex,
		size_t	elementIndex
	)

Remove an element from the array.

Parameters

rowIndex	The row number where the element is stored.
elementIndex	The element number inside this row to remove.

◆ RemoveRow()

template<class T >

void Array2D::RemoveRow	(	size_t	rowIndex,
		bool	autoShrink = `false`
	)

Remove a given row, including all its elements. This will decrease the number of rows.

Parameters

rowIndex	The row number to remove.
autoShrink	When set to true, the array's memory usage will be optimized and minimized as much as possible.

◆ RemoveRows()

template<class T >

void Array2D::RemoveRows	(	size_t	startRow,
		size_t	endRow,
		bool	autoShrink = `false`
	)

Remove a given range of rows and all their elements. All rows from the specified start row until the end row will be removed, with the start and end rows included.

Parameters

startRow	The start row number to start removing from (so this one will also be removed).
endRow	The end row number (which will also be removed).
autoShrink	When set to true, the array's memory usage will be optimized and minimized as much as possible.

◆ Resize()

template<class T >

void Array2D::Resize	(	size_t	numRows,
		bool	autoShrink = `false`
	)

Resize the array in one dimension (the number of rows). Rows that will be added willl automatically get [n] number of elements pre-allocated. The number of [n] can be set with the SetNumPreCachedElements(...) method. Please note that the pre-allocated/cached elements are not valid to be used yet. You have to use the Add method first.

Parameters

numRows	The number of rows you wish to init for.
autoShrink	When set to true, after execution of this method the Shrink method will automatically be called in order to optimize the memory usage. This only happens when resizing to a lower amount of rows, so when making the array smaller.

◆ SetElement()

template<class T >

void MCore::Array2D< T >::SetElement	(	size_t	rowIndex,
		size_t	elementNr,
		const T &	value
	)

inline

Set the value for a given element in the array.

Parameters

rowIndex	The row where the element is stored in.
elementNr	The element number to set the value for.
value	The value to set the element to.

◆ SetNumPreCachedElements()

template<class T >

void MCore::Array2D< T >::SetNumPreCachedElements ( size_t numElemsPerRow )

inline

Set the number of elements per row that should be pre-allocated/cached when creating / adding new rows. This doesn't actually increase the number of elements for a given row, but just reserves memory for the elements, which can speedup adding of new elements and prevent memory reallocs. The default value is set to 2 when creating an array, unless specified differently.

Parameters

numElemsPerRow The number of elements per row that should be pre-allocated.

◆ Shrink()

template<class T >

void Array2D::Shrink ( )

Optimize (minimize) the memory usage of the array. This will move all elements around, removing all gaps and unused pre-cached/allocated items. It is advised to call this method after you applied some heavy modifications to the array, such as removing rows or many elements. When your array data is fairly static, and you won't be adding or removing data from it very frequently, you should definitely call this method after you have filled the array with data.

◆ Swap()

template<class T >

void Array2D::Swap	(	size_t	rowA,
		size_t	rowB
	)

Swap the element data of two rows. Beware, this is pretty slow!

Parameters

rowA	The first row.
rowB	The second row.

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

Gems/EMotionFX/Code/MCore/Source/Array2D.h
Gems/EMotionFX/Code/MCore/Source/Array2D.inl

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Array2D() [1/2]

◆ Array2D() [2/2]

Member Function Documentation

◆ Add()

◆ CalcTotalNumElements()

◆ CalcUsedElementMemoryPercentage()

◆ Clear()

◆ GetData()

◆ GetElement() [1/2]

◆ GetElement() [2/2]

◆ GetElements()

◆ GetIndexTable()

◆ GetNumElements()

◆ GetNumPreCachedElements()

◆ GetNumRows()

◆ LogContents()

◆ Remove()

◆ RemoveRow()

◆ RemoveRows()

◆ Resize()

◆ SetElement()

◆ SetNumPreCachedElements()

◆ Shrink()

◆ Swap()