FbxArray< T, Alignment > Class Template Reference

Class for array of basic elements such as pointers and basic types. More...

#include <fbxarray.h>

Classes
struct	tData

Public Types
typedef int(*	CompareFunc) (const void *, const void *)
	Element compare function pointer definition. More...

Public Member Functions
	FbxArray ()
	Constructor. More...
	FbxArray (const int pCapacity)
	Reserve constructor. More...
	FbxArray (const FbxArray &pArray)
	Copy constructor. More...
	~FbxArray ()
	Destructor. More...
int	InsertAt (const int pIndex, const T &pElement, bool pCompact=false)
	Insert an element at the given position, growing the array if capacity is not sufficient. More...
int	Add (const T &pElement)
	Append an element at the end of the array, doubling the array if capacity is not sufficient. More...
int	AddUnique (const T &pElement)
	Append an element at the end of array, if not already present, doubling the array if capacity is not sufficient. More...
int	AddCompact (const T &pElement)
	Append an element at the end of the array, growing the array by one element if capacity is not sufficient. More...
int	Size () const
	Retrieve the number of element contained in the array. More...
int	Capacity () const
	Retrieve the current allocated memory capacity of the array. More...
T &	operator[] (const int pIndex) const
	Retrieve a reference of the element at given index position in the array. More...
T	GetAt (const int pIndex) const
	Retrieve a copy of the element at given index position in the array. More...
T	GetFirst () const
	Retrieve a copy of the first element. More...
T	GetLast () const
	Retrieve a copy of the last element. More...
int	Find (const T &pElement, const int pStartIndex=0) const
	Find first matching element, from first to last. More...
int	FindReverse (const T &pElement, const int pStartIndex=0x7fffffff) const
	Find first matching element, from last to first. More...
bool	Reserve (const int pCapacity)
	Request for allocation of additional memory without inserting new elements. More...
void	SetAt (const int pIndex, const T &pElement)
	Set the element at given position in the array. More...
void	SetFirst (const T &pElement)
	Set the value of the first element. More...
void	SetLast (const T &pElement)
	Set the value of the last element. More...
T	RemoveAt (const int pIndex)
	Remove an element at the given position in the array. More...
T	RemoveFirst ()
	Remove the first element in the array. More...
T	RemoveLast ()
	Remove the last element in the array. More...
bool	RemoveIt (const T &pElement)
	Remove first matching element in the array. More...
void	RemoveRange (const int pIndex, const int pCount)
	Remove a range of elements at the given position in the array. More...
bool	ResizeUninitialized (const int pSize, bool pPreserveCapacityIfPossible=false)
	Inserts or erases elements at the end such that Size() becomes pSize, increasing capacity if needed. More...
bool	Resize (const int pSize, bool pPreserveCapacityIfPossible=false)
	Inserts or erases elements at the end such that Size() becomes pSize, increasing capacity if needed. More...
bool	Grow (const int pSize)
	Increase size of array by the specified size. More...
bool	Shrink (const int pSize)
	Reduce size of array by the specified size. More...
bool	Compact ()
	Compact the array so that its capacity is the same as its size. More...
void	Clear ()
	Reset the number of element to zero and free the memory allocated. More...
void	Sort (CompareFunc pCompareFunc)
	Sort the array using the specified compare function pointer. More...
T *	GetArray () const
	Get pointer to internal array of elements. More...
	operator T * () const
	Cast operator. More...
void	AddArray (const FbxArray< T > &pOther)
	Append another array at the end of this array. More...
void	AddArrayNoDuplicate (const FbxArray< T > &pOther)
	Append the elements of another array at the end of this array if they are not present. More...
void	RemoveArray (const FbxArray< T > &pOther)
	Remove the elements of another array from this array is they are present. More...
FbxArray< T > &	operator= (const FbxArray< T > &pOther)
	Operator to copy elements of an array. More...
bool	operator== (const FbxArray< T > &pOther) const
	Operator to compare elements of an array. More...

Protected Attributes
struct FbxArray::tData *	mData

Detailed Description

template<class T, const int Alignment = 16>
class FbxArray< T, Alignment >

Class for array of basic elements such as pointers and basic types.

This class will not call constructor and destructor for elements, thus it is not suitable for object references. Memory allocations are always done in a single contiguous memory region.

Examples:

ExportScene03/main.cxx, SwitchBinding/main.cxx, ViewScene/main.cxx, ViewScene/SceneCache.h, ViewScene/SceneContext.cxx, and ViewScene/SceneContext.h.

Definition at line 37 of file fbxarray.h.

Member Typedef Documentation

typedef int(* CompareFunc) (const void *, const void *)

Element compare function pointer definition.

Definition at line 52 of file fbxarray.h.

Constructor & Destructor Documentation

FbxArray ( )

inline

Constructor.

Definition at line 55 of file fbxarray.h.

: mData(NULL){}

FbxArray ( const int  pCapacity )

inline

Reserve constructor.

Definition at line 58 of file fbxarray.h.

: mData(NULL){ if( pCapacity > 0 ) Reserve(pCapacity); }

FbxArray ( const FbxArray< T, Alignment > &  pArray )

inline

Copy constructor.

Definition at line 61 of file fbxarray.h.

: mData(NULL){ *this = pArray; }

~FbxArray ( )

inline

Destructor.

Remarks

The destructor for each element will not be called.

Definition at line 65 of file fbxarray.h.

{ Clear(); }

Member Function Documentation

int InsertAt ( const int  pIndex, const T &  pElement, bool  pCompact = false  )

inline

Insert an element at the given position, growing the array if capacity is not sufficient.

Parameters

pIndex	Position where to insert the element. Must be a positive value.
pElement	Element to insert in the array.
pCompact	If true and capacity is exceeded, grow capacity by one, otherwise double capacity (default).

Returns

-1 if insert failed, otherwise the position of the inserted element in the array.

Remarks

If the given index is greater than Size(), the element is appended at the end. Use compact mode only if you need to save memory.

Definition at line 73 of file fbxarray.h.

    {
        FBX_ASSERT_RETURN_VALUE(pIndex >= 0, -1);
        int lIndex = FbxMin(pIndex, GetSize());
        if( GetSize() >= GetCapacity() )
        {
            T lElement = pElement;    //Copy element because we might move memory
            int lNewCapacity = FbxMax(pCompact ? GetCapacity() + 1 : GetCapacity() * 2, 1);    //We always double capacity when not compacting
            Allocate(lNewCapacity);
            FBX_ASSERT_RETURN_VALUE(mData, -1);
            mData->mCapacity = lNewCapacity;
            return InsertAt(pIndex, lElement);    //Insert copied element because reference might be moved
        }

        if( lIndex < GetSize() )    //Move elements to leave a space open to insert the new element
        {
            //If pElement is inside memmove range, copy element and insert copy instead
            if( (&pElement >= &GetArray()[lIndex]) && (&pElement < &GetArray()[GetSize()]) )
            {
                T lElement = pElement;
                return InsertAt(pIndex, lElement);
            }
            memmove(&GetArray()[lIndex + 1], &GetArray()[lIndex], (GetSize() - lIndex) * sizeof(T));
        }

        memcpy(&GetArray()[lIndex], &pElement, sizeof(T));
        mData->mSize++;

        return lIndex;
    }

int Add ( const T &  pElement )

inline

Append an element at the end of the array, doubling the array if capacity is not sufficient.

Parameters

pElement

Element to append to the array.

Returns

-1 if add failed, otherwise the position of the added element in the array.

Remarks

This function is the optimized version of InsertAt(GetSize(), pElement) which, by skipping some validation tests, can provide up to 33% speed gains.

Definition at line 108 of file fbxarray.h.

    {
        int lIndex = GetSize();

        if (lIndex >= GetCapacity())
        {
            T lElement = pElement;    //Copy element because we might move memory
            int lNewCapacity = FbxMax(GetCapacity() * 2, 1);    //We always double capacity
            Allocate(lNewCapacity);
            FBX_ASSERT_RETURN_VALUE(mData, -1);
            mData->mCapacity = lNewCapacity;
            return Add(lElement);    //Insert copied element because reference might be moved
        }

        memcpy(&GetArray()[lIndex], &pElement, sizeof(T));
        mData->mSize++;

        return lIndex;
    }

int AddUnique ( const T &  pElement )

inline

Append an element at the end of array, if not already present, doubling the array if capacity is not sufficient.

Parameters

pElement

Element to append to the array.

Returns

-1 if add failed, otherwise the position of the added element in the array.

Definition at line 131 of file fbxarray.h.

    {
        int lIndex = Find(pElement);
        return ( lIndex == -1 ) ? Add(pElement) : lIndex;
    }

int AddCompact ( const T &  pElement )

inline

Append an element at the end of the array, growing the array by one element if capacity is not sufficient.

Parameters

pElement

Element to append to the array.

Returns

-1 if add failed, otherwise the position of the added element in the array.

Definition at line 140 of file fbxarray.h.

    {
        return InsertAt(GetSize(), pElement, true);
    }

int Size ( ) const

inline

Retrieve the number of element contained in the array.

To increase the capacity without increasing the size, please use Reserve().

Returns

The number of element in the array.

Remarks

The size of the array cannot exceed its capacity.

Definition at line 148 of file fbxarray.h.

{ return GetSize(); }

int Capacity ( ) const

inline

Retrieve the current allocated memory capacity of the array.

Returns

The capacity of the array in number of element.

Remarks

The capacity will always be greater or equal to its size.

Definition at line 153 of file fbxarray.h.

{ return GetCapacity(); }

T& operator[] ( const int  pIndex ) const

inline

Retrieve a reference of the element at given index position in the array.

Parameters

pIndex

Position of element in the array.

Returns

A reference to the element at the specified position in the array.

Remarks

No error will be thrown if the index is out of bounds.

Definition at line 159 of file fbxarray.h.

    {
        if (pIndex < 0)
        {
            FBX_THROW("Index is out of range!");
        }

        if (pIndex >= GetSize())
        {
            if (pIndex < GetCapacity())
            {
                FBX_THROW("Index is out of range, but not outside of capacity! Call SetAt() to use reserved memory.");
            }

            FBX_THROW("Index is out of range!");
        }

        return GetArray()[pIndex];
    }

T GetAt ( const int  pIndex ) const

inline

Retrieve a copy of the element at given index position in the array.

Parameters

pIndex

Position of element in the array.

Returns

The value of the element at the specified position in the array.

Remarks

No error will be thrown if the index is out of bounds.

Definition at line 183 of file fbxarray.h.

    {
        return operator[](pIndex);
    }

T GetFirst ( ) const

inline

Retrieve a copy of the first element.

Returns

Copy of the first element.

Remarks

The array should have at least one element and no error will be thrown if the array is empty.

Definition at line 191 of file fbxarray.h.

    {
        return GetAt(0);
    }

T GetLast ( ) const

inline

Retrieve a copy of the last element.

Returns

Copy of the last element.

Remarks

The array should have at least one element and no error will be thrown if the array is empty.

Definition at line 199 of file fbxarray.h.

    {
        return GetAt(GetSize() - 1);
    }

int Find ( const T &  pElement, const int  pStartIndex = 0  ) const

inline

Find first matching element, from first to last.

Parameters

pElement	The element to be compared to each of the elements.
pStartIndex	The position to start searching from.

Returns

Position of first matching element or -1 if there is no matching element.

Definition at line 208 of file fbxarray.h.

    {
        const int size = GetSize();

        FBX_ASSERT_RETURN_VALUE(pStartIndex >= 0, -1);
        FBX_ASSERT_RETURN_VALUE(size >= 0, -1);

        for (int i = pStartIndex; i < size; ++i)
        {
            if (GetArray()[i] == pElement) return i;
        }
        return -1;
    }

int FindReverse ( const T &  pElement, const int  pStartIndex = 0x7fffffff  ) const

inline

Find first matching element, from last to first.

Parameters

pElement	The element to be compared to each of the elements.
pStartIndex	The position to start searching from.

Returns

Position of first matching element or -1 if there is no matching element.

Definition at line 226 of file fbxarray.h.

    {
        const int size = GetSize();

        FBX_ASSERT_RETURN_VALUE(size > 0, -1);

        for (int i = FbxMin(pStartIndex, size - 1); i >= 0; --i)
        {
            if (GetArray()[i] == pElement) return i;
        }
        return -1;
    }

bool Reserve ( const int  pCapacity )

inline

Request for allocation of additional memory without inserting new elements.

After the memory has been reserved, please use SetAt() to initialize elements.

Parameters

pCapacity

The number of additional element memory allocation requested.

Returns

true if the memory allocation succeeded or if the capacity is unchanged, false otherwise.

Remarks

If the requested capacity is less than or equal to the current capacity, this call has no effect. In either case, Size() is unchanged.

Definition at line 243 of file fbxarray.h.

    {
        FBX_ASSERT_RETURN_VALUE(pCapacity >= 0, false);
        if( pCapacity > GetCapacity() )
        {
            Allocate(pCapacity);
            FBX_ASSERT_RETURN_VALUE(mData, false);
            mData->mCapacity = pCapacity;

            //Initialize new memory to zero
            memset(&GetArray()[GetSize()], 0, (GetCapacity() - GetSize()) * sizeof(T));
        }
        return true;
    }

void SetAt ( const int  pIndex, const T &  pElement  )

inline

Set the element at given position in the array.

Parameters

pIndex	Position of element in the array.
pElement	The new element.

Remarks

If the index is outside range, and outside capacity, this call has no effect. However, if index is within capacity range, element count is increased such that Size() will become pIndex + 1.

Definition at line 263 of file fbxarray.h.

    {
        FBX_ASSERT_RETURN(pIndex >= 0 && pIndex < GetCapacity());
        if( pIndex >= GetSize() ) mData->mSize = pIndex + 1;

        T* const array = GetArray();
        if (array) memcpy(&array[pIndex], &pElement, sizeof(T));
    }

void SetFirst ( const T &  pElement )

inline

Set the value of the first element.

Parameters

pElement

The new value of the last element.

Remarks

The array should have at least one element and no error will be thrown if the array is empty.

Definition at line 275 of file fbxarray.h.

    {
        SetAt(0, pElement);
    }

void SetLast ( const T &  pElement )

inline

Set the value of the last element.

Parameters

pElement

The new value of the last element.

Remarks

The array should have at least one element and no error will be thrown if the array is empty.

Definition at line 283 of file fbxarray.h.

    {
        SetAt(GetSize() - 1, pElement);
    }

T RemoveAt ( const int  pIndex )

inline

Remove an element at the given position in the array.

Parameters

pIndex

Position of the element to remove.

Returns

Removed element.

Remarks

No error will be thrown if the index is out of bounds.

Definition at line 292 of file fbxarray.h.

    {
        const int size = GetSize();
        const int index = pIndex + 1;
        if (index < 0 || index > size)
        {
            FBX_THROW("Index is out of range!");
        }

        T lElement = GetAt(pIndex);
        if (index < size)
        {
            memmove(&GetArray()[pIndex], &GetArray()[index], (size - pIndex - 1) * sizeof(T));
        }
        mData->mSize--;
        return lElement;
    }

T RemoveFirst ( )

inline

Remove the first element in the array.

Returns

Removed element.

Remarks

The array should have at least one element and no error will be thrown if the array is empty.

Definition at line 313 of file fbxarray.h.

    {
        return RemoveAt(0);
    }

T RemoveLast ( )

inline

Remove the last element in the array.

Returns

Removed element.

Remarks

The array should have at least one element and no error will be thrown if the array is empty.

Definition at line 321 of file fbxarray.h.

    {
        return RemoveAt(GetSize() - 1);
    }

bool RemoveIt ( const T &  pElement )

inline

Remove first matching element in the array.

Parameters

pElement

Element to be removed.

Returns

true if a matching element is found and removed, false otherwise.

Definition at line 329 of file fbxarray.h.

    {
        int Index = Find(pElement);
        if( Index >= 0 )
        {
            RemoveAt(Index);
            return true;
        }
        return false;
    }

void RemoveRange ( const int  pIndex, const int  pCount  )

inline

Remove a range of elements at the given position in the array.

Parameters

pIndex	Begin position of the elements to remove.
pCount	The count of elements to remove.

Returns

true if successful, otherwise false.

Remarks

This function re-use the memory already allocated

Definition at line 345 of file fbxarray.h.

    {
        const int size = GetSize();
        if (size == 0)
            // the array is already empty (or not allocated yet)
            // no point in continuing
            return;

        FBX_ASSERT(GetArray() != NULL);
        FBX_ASSERT_RETURN(pCount >  0);
        FBX_ASSERT_RETURN(pIndex >= 0);

        size_t lastItem = pIndex + pCount;
        FBX_ASSERT_RETURN(lastItem >= 0);
        FBX_ASSERT_RETURN(lastItem <= (size_t)size);
        FBX_ASSERT_RETURN(lastItem < FBXSDK_INT_MAX);

        if (lastItem < (size_t)size)
        {
            memmove(&GetArray()[pIndex], &GetArray()[pIndex + pCount], (size - pIndex - pCount) * (unsigned)sizeof(T));
        }

        if (mData)
        {
            mData->mSize -= pCount;
        }
    }

bool ResizeUninitialized ( const int  pSize, bool  pPreserveCapacityIfPossible = false  )

inline

Inserts or erases elements at the end such that Size() becomes pSize, increasing capacity if needed.

Please use SetAt() to initialize any new elements.

Parameters

pSize	The new count of elements to set the array to. Must be greater or equal to zero.
pPreserveCapacityIfPossible	If the new count will fit into the existing allocation, do not adjust the capacity.

Returns

true if the memory (re)allocation succeeded, false otherwise.

Remarks

If the requested element count is less than or equal to the current count, elements are freed from memory. Otherwise, the array grows and elements are unchanged. The new array memory is not cleared to 0.

Definition at line 378 of file fbxarray.h.

    {
        if( pSize == GetSize() && GetSize() == GetCapacity() ) return true;

        if( pSize == 0 )
        {
            Clear();
            return true;
        }

        FBX_ASSERT_RETURN_VALUE(pSize > 0, false);

        bool lReallocate;
        if (pPreserveCapacityIfPossible)
            lReallocate = pSize > GetCapacity();
        else
            lReallocate = pSize != GetCapacity();
        
        if (lReallocate)
        {
            Allocate(pSize);
            FBX_ASSERT_RETURN_VALUE(mData, false);
            mData->mCapacity = pSize;
        }

        mData->mSize = pSize;
        return true;
    }

bool Resize ( const int  pSize, bool  pPreserveCapacityIfPossible = false  )

inline

Inserts or erases elements at the end such that Size() becomes pSize, increasing capacity if needed.

Please use SetAt() to initialize any new elements.

Parameters

pSize	The new count of elements to set the array to. Must be greater or equal to zero.
pPreserveCapacityIfPossible	If the new count will fit into the existing allocation, do not adjust the capacity.

Returns

true if the memory (re)allocation succeeded, false otherwise.

Remarks

If the requested element count is less than or equal to the current count, elements are freed from memory. Otherwise, the array grows and elements are unchanged.

Definition at line 412 of file fbxarray.h.

    {
        if (pSize == GetSize() && GetSize() == GetCapacity()) return true;

        if (pSize == 0)
        {
            Clear();
            return true;
        }

        FBX_ASSERT_RETURN_VALUE(pSize > 0, false);

        bool lReallocate;
        if (pPreserveCapacityIfPossible)
            lReallocate = pSize > GetCapacity();
        else
            lReallocate = pSize != GetCapacity();

        if (lReallocate)
        {
            Allocate(pSize);
            FBX_ASSERT_RETURN_VALUE(mData, false);

            if (pSize > GetCapacity())    //Initialize new memory to zero
            {
                memset(&GetArray()[GetSize()], 0, (pSize - GetSize()) * sizeof(T));
            }
        
            mData->mCapacity = pSize;
        }

        mData->mSize = pSize;
        return true;
    }

bool Grow ( const int  pSize )

inline

Increase size of array by the specified size.

Parameters

pSize

The size to add to the array size.

Returns

true if operation succeeded, false otherwise.

Definition at line 450 of file fbxarray.h.

    {
        const int size = GetSize();

        // Check int32 paramater does not overflow
        FbxLongLong newSize = static_cast<FbxLongLong>(size) + static_cast<FbxLongLong>(pSize);
        if (newSize > INT_MAX)
        {
            return false;
        }

        return Resize(size + pSize);
    }

bool Shrink ( const int  pSize )

inline

Reduce size of array by the specified size.

Parameters

pSize

The size to remove from the array size.

Returns

true if operation succeeded, false otherwise.

Definition at line 467 of file fbxarray.h.

    {
        const int size = GetSize();

        // Check int32 paramater does not overflow
        FbxLongLong newSize = static_cast<FbxLongLong>(size) - static_cast<FbxLongLong>(pSize);
        if (pSize < 0 || newSize < 0 || newSize > size)
        {
            return false;
        }

        return Resize(size - pSize);
    }

bool Compact ( )

inline

Compact the array so that its capacity is the same as its size.

Returns

true if operation succeeded, false otherwise.

Definition at line 483 of file fbxarray.h.

    {
        return Resize(GetSize());
    }

void Clear ( )

inline

Reset the number of element to zero and free the memory allocated.

Remarks

This only free the memory allocated by the array, and doesn't call the destructor of each element.

Definition at line 490 of file fbxarray.h.

    {
        if( mData != NULL )
        {
            FbxFree(mData);
            mData = NULL;
        }
    }

void Sort ( CompareFunc  pCompareFunc )

inline

Sort the array using the specified compare function pointer.

Parameters

pCompareFunc

The compare function to use to sort elements.

Definition at line 501 of file fbxarray.h.

    {
        qsort(GetArray(), GetSize(), sizeof(T), pCompareFunc);
    }

T* GetArray ( ) const

inline

Get pointer to internal array of elements.

Definition at line 507 of file fbxarray.h.

{ return mData ? &mData->mArray[0] : NULL; }

operator T * ( ) const

inline

Cast operator.

Definition at line 510 of file fbxarray.h.

{ return GetArray(); }

void AddArray ( const FbxArray< T > &  pOther )

inline

Append another array at the end of this array.

Parameters

pOther

The other array to append to this array.

Definition at line 514 of file fbxarray.h.

    {
        if( Grow(pOther.GetSize()) )
        {
            memcpy(&GetArray()[GetSize() - pOther.GetSize()], pOther.GetArray(), pOther.GetSize() * sizeof(T));
        }
    }

void AddArrayNoDuplicate ( const FbxArray< T > &  pOther )

inline

Append the elements of another array at the end of this array if they are not present.

Parameters

pOther

Another array.

Definition at line 524 of file fbxarray.h.

    {
        for( int i = 0, c = pOther.GetSize(); i < c; ++i )
        {
            AddUnique(pOther[i]);
        }
    }

void RemoveArray ( const FbxArray< T > &  pOther )

inline

Remove the elements of another array from this array is they are present.

Parameters

pOther

Another array.

Definition at line 534 of file fbxarray.h.

    {
        for( int i = 0, c = pOther.GetSize(); i < c; ++i )
        {
            RemoveIt(pOther[i]);
        }
    }

FbxArray<T>& operator= ( const FbxArray< T > &  pOther )

inline

Operator to copy elements of an array.

Returns

this array containing a copy of pOther elements.

Definition at line 544 of file fbxarray.h.

    {
        if( this != &pOther )
        {
            if( Resize(pOther.GetSize()) )
            {
                memcpy(GetArray(), pOther.GetArray(), pOther.GetSize() * sizeof(T));
            }
        }
        return *this;
    }

bool operator== ( const FbxArray< T > &  pOther ) const

inline

Operator to compare elements of an array.

Returns

true if the two arrays are equal, otherwise false.

Definition at line 558 of file fbxarray.h.

    {
        if( this == &pOther ) return true;
        if( GetSize() != pOther.GetSize() ) return false;
        return memcmp(GetArray(), pOther.GetArray(), sizeof(T) * GetSize()) == 0;
    }

Member Data Documentation

struct FbxArray::tData * mData

protected

---

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

• fbxsdk/core/base/fbxarray.h