Store< type > Class Template Reference

#include <array.h>

Class Description

template<typename type>
class mudbox::Store< type >

Simple array class.

This class represents a simple array and should be used in all circumstances instead of plain C-style arrays. The class is templated, so that you can use to instantiate arrays of any type.

Its advantages of Store arrays include:

• when the object is deleted, the associated data is deleted automatically. This means that if the Store instance was created on the heap, or it is a member variable of another class, then you don't have to bother freeing the memory, reducing the chance of a memory leak.

• Additional functionality, such as expandability, sorting, and removing specified elements.

• Easy to serialize.

• The mudbox kernel can examine the list of all Store arrays in the memory at any time, which is helpful for diagnosing high memory footprint problems, as well as memory leaks.

Typical usage:

Typically, you create an empty Store instance, and then set the number of items (if you know it) by calling SetItemCount(). Alternatively, you can add elements into the array one by one, using the Add() function. If the elements of the array are class instances, their constructors and destructors can optionally be called when the array space is allocated and deallocated. (You must call the right methods.) For this reason, any class from which you will create an array should have a constructor that takes no arguments.

When the array is extended (for example when new elements are added by calling the Add() function), the existing array elements will be copied to the new location with the "=" operator of the element class. For this reason, you should ensure that this operator will work correctly, especially in cases where your class contains pointers. (If you have no "-" operator defined in the data class, it will just do a direct memory copy.)

A Store instance sometimes has more memory allocated than needed by the number of elements in the array. See the Optimize() function for more details.

Note: If you use the "=" operator to copy one entire Store array to another, the original array is left empty. (This is a speed optimization.) If you want to do a deep copy of the contents of the Store array, you should instead use the Clone() function as follows:

Store<int> a;
a = b.Clone();

Examples:

Definition at line 334 of file array.h.

Inheritance diagram for Store< type >:

Public Member Functions
	Store (const char *sName="unknown")
	Creates an empty array. More...
	Store (unsigned int iSize, const char *sName)
	Creates an array with space for some elements already allocated. More...
	Store (const type *pArray, int iSize, const char *sName="unknown")
	Creates an array and populates it will information copied from another array. More...
	Store (bool bNoObjects, const char *sName)
	Creates an empty array, allowing you to specify if elements have constructors or destructors that need to be called. More...
	Store (const Store &s)
	Creates an array from another one. The other array becomes empty after the operation. More...
	~Store (void)
	Destroys the contents of the array and deallocate its memory. More...
bool	Copy (Store &s) const
	Copies the contents of another array into this one, duplicating all data. Returns true if successful. More...
Store	Clone (void) const
	Returns a copy of this array. The returned copy will have a duplicate of all data in the original. More...
void	Clone (Store &s) const
	Copies the contents of another array into this one, duplicating all data. More...
void	Clear (bool bDestruct=false)
	Clears the array and deallocates its memory. More...
bool	SetItemCount (unsigned int iSize, bool bKeepContent=false)
	Sets the logical size of the array. More...
bool	Allocate (unsigned int iSize, bool bKeepContent=false)
	Preallocates memory for the an array, without changing the array's logical size. More...
bool	Extend (unsigned int iIndex)
	Extends the logical size of the array. More...
bool	Extend (int iIndex)
	Extends the logical size of the array. More...
void	RemoveTail (int iItemCount=1)
	Removes the final items from the array. More...
void	Fill (type cPattern)
	Fills the array with a specified element. More...
void	ByteFill (unsigned char cPattern)
	Fills the array with a specified byte pattern. More...
unsigned int	Add (const type &e)
	Adds a new item to the array, increasing the array size by 1. More...
unsigned int	Add (type &e)
	Adds a new item to the array, increasing the array size by 1. More...
Store &	operator= (const Store &s)
	Transfers the contents of another array to this one, leaving the original array empty. More...
void	GetFrom (Store &s)
	Transfers the contents of another array to this one, leaving the original array empty. More...
const type &	operator[] (unsigned int iIndex) const
	Returns an indexed item from the array. More...
type &	operator[] (unsigned int iIndex)
	Returns an indexed item from the array. More...
const type &	operator[] (int iIndex) const
	Returns an indexed item from the array. More...
type &	operator[] (int iIndex)
	Returns an indexed item from the array. More...
bool	IsEmpty (void) const
	Returns true if the array has no items. More...
	operator bool (void) const
	Allows you to use the array as a boolean in if statements. Evaluates to true if the array is not empty. More...
bool	operator! (void) const
	Evaluates to true if the array contains no items. More...
void	SetBuffer (type *pData, unsigned int iSize=0)
	Makes a Store array from a regular C or C++ array. More...
void	Serialize (class Stream &s)
	Serializes the the array and its contents from/to a stream. More...
void	Sort (void)
	Sorts the items in the array. More...
type *	Find (type a)
	Returns a pointer to the item in the array with a particular value. More...
type *	Find (type *a)
	Returns a pointer to the item in the array with a particular value. More...
unsigned int	IndexOf (type pValue)
	Returns the first index of the element equal to pValue. More...
unsigned int	Remove (const type &e)
	Remove every occurrence of a specified item from the array. Returns the number of removed items. More...
void	RemoveAt (unsigned int iIndex)
	Removes the item at the specified index from the array. More...
unsigned int	RemoveDuplicates (void)
	Removes duplicated items from the array after sorting it. More...
unsigned int	ItemCount (void) const
	Returns the number of items in the array. More...
type &	Last (void)
	Returns the last item in the array, or 0 if the array is empty. More...
void	Optimize (void)
	Reduces the allocated memory size to match the size of the current elements in the array. More...
Public Member Functions inherited from Array< type >
	Array (const char *sName)
	Array (const char *sName, unsigned int iSize)
	Array (const char *sName, const type *pArray, int iSize)
	Array (const char *sName, bool bNoObjects)
	Array (const char *sName, const Array< type > &a)
void	Clear (bool bDestruct=false)
Array< type >	Clone (void) const
bool	Copy (Array< type > &a) const
void	Set (unsigned int iStart, unsigned int iSize, unsigned char cPattern)
bool	Extend (unsigned int iElementIndex)
bool	Alloc (unsigned int iNewSize)
type &	operator[] (int iIndex)
type &	operator[] (unsigned int iIndex)
const type &	operator[] (unsigned int iIndex) const
type *	indexedAddr (unsigned int i)
const type *	indexedAddr (unsigned int i) const
type *	baseAddr ()
const type *	baseAddr () const
void	operator= (const Array< type > &a)
	~Array (void)
Public Member Functions inherited from Block
const Block *	Next (void) const
unsigned int	ItemSize (void) const
const char *	Name (void) const
long long	Size (void) const
long long	Address (void) const
void	Check (void) const

Public Attributes
unsigned int	m_iSize
Public Attributes inherited from Block
const char *	m_sName

Static Protected Member Functions
static int	Compare (const void *a, const void *b)

Additional Inherited Members
Static Public Member Functions inherited from Block
static const Block *	Head (void)
static void	LogAll (float fSizeFilter=0.01f, bool bSortByAddress=false)
static void	CheckAll (void)
static bool	RegisterMemoryBlock (long long iSize)
static bool	UnregisterMemoryBlock (long long iSize)
static void	SetAllocatorID (const char *pAllocatorID)
static void	CopyMemoryBlock (void *pDestination, const void *pSource, long long iSize)
static void *	AlignedAlloc (size_t iBytes, unsigned int iAlignment)
static void	AlignedFree (void *pData)
Protected Member Functions inherited from Block
	Block (const char *sName, unsigned int iItemSize)
	~Block (void)
Protected Attributes inherited from Array< type >
type *	m_pArray
unsigned int	m_iSize
bool	m_bData
const Array< type > *	m_pThis
Protected Attributes inherited from Block
Block *	m_pNext
Block *	m_pPrev
unsigned int	m_iItemSize
Static Protected Attributes inherited from Block
static Block *	s_pHead

Constructor & Destructor Documentation

Store ( const char *  sName = "unknown" )

inline

Creates an empty array.

Parameters

[in]

sName

A name for the array (optional). Displayed in the log only.

Definition at line 338 of file array.h.

          : Array<type>( sName ) { m_iSize = 0; };

Store ( unsigned int  iSize, const char *  sName  )

inline

Creates an array with space for some elements already allocated.

The content of the array is undefined. (That is, constructors are not called. To create an array where constructors and destructors are called automatically, use this call:

Store<myType> myInstance(false);

Parameters

[in]	iSize	The number of elements to allocate initially.
[in]	sName	A name for the array (optional). Displayed in the log only.

Definition at line 350 of file array.h.

          : Array<type>( sName, iSize ) { m_iSize = iSize; };

Store ( const type *  pArray, int  iSize, const char *  sName = "unknown"  )

inline

Creates an array and populates it will information copied from another array.

Note that the information from the source array is copied over using memcpy. It is the caller's responsibility to check that the array being copied from contains enough values to copy before calling this constructor.

Parameters

[in]	pArray	The array from which to copy elements
[in]	iSize	The number of elements to copy over
[in]	sName	A name for the array (optional). Displayed in the log only.

Definition at line 360 of file array.h.

          : Array<type>( sName, pArray, iSize ) { m_iSize = iSize; };

Store ( bool  bNoObjects, const char *  sName  )

inline

Creates an empty array, allowing you to specify if elements have constructors or destructors that need to be called.

Parameters

[in]	bNoObjects	if true, constructors and destructors will not be called on the array objects.
[in]	sName	A name for the array (optional). Displayed in the log only.

Definition at line 367 of file array.h.

          : Array<type>( sName, bNoObjects ) { m_iSize = 0; };

Store ( const Store< type > &  s )

inline

Creates an array from another one. The other array becomes empty after the operation.

Parameters

[in]

s

The array whose contents will be transferred to this one

Definition at line 373 of file array.h.

          : Array<type>( s.m_sName, s ) { m_iSize = s.m_iSize; s.m_iSize = 0; };

~Store ( void  )

inline

Destroys the contents of the array and deallocate its memory.

Definition at line 378 of file array.h.

{ Clear( !Array<type>::m_bData ); };

Member Function Documentation

bool Copy ( Store< type > &  s ) const

inline

Copies the contents of another array into this one, duplicating all data. Returns true if successful.

Parameters

[in]

s

The array to be duplicated

Definition at line 381 of file array.h.

                { s.m_iSize = m_iSize; return Array<type>::Copy( s ); };

Store Clone ( void  ) const

inline

Returns a copy of this array. The returned copy will have a duplicate of all data in the original.

Definition at line 386 of file array.h.

{ Store s; s.SetItemCount( m_iSize ); Copy( s ); return s; };

void Clone ( Store< type > &  s ) const

inline

Copies the contents of another array into this one, duplicating all data.

Parameters

[in]

s

The array to be duplicated

Definition at line 389 of file array.h.

                { s.SetItemCount( m_iSize ); Copy( s ); };

void Clear ( bool  bDestruct = false )

inline

Clears the array and deallocates its memory.

Parameters

[in]

bDestruct

If true, the destructor will be called for each element.

Definition at line 394 of file array.h.

          { Array<type>::Clear( bDestruct ); m_iSize = 0; };

bool SetItemCount ( unsigned int  iSize, bool  bKeepContent = false  )

inline

Sets the logical size of the array.

Returns true if successful.

If the new size is smaller than the current size, items at the end of the array will be discarded. If the new size is larger, then a new memory block will be allocated. In this case, the existing items will only be copied to the new block only if bKeepContent is set to true.

Parameters

[in]	iSize	The new size of the array
[in]	bKeepContent	if true, the original array contents will be preserved when the array size is increased.

Definition at line 403 of file array.h.

    { 
        if ( iSize <= m_iSize )
        {
            m_iSize = iSize;
            return true;
        };
        if ( !bKeepContent ) 
            Clear(); 
        if ( Array<type>::Alloc( iSize ) ) 
        { 
            m_iSize = iSize; 
            return true; 
        };
        return false;
    };

bool Allocate ( unsigned int  iSize, bool  bKeepContent = false  )

inline

Preallocates memory for the an array, without changing the array's logical size.

Returns true if successful.

This method can be used to increase efficiency when an array is expected to grow by a large number of small steps. For example, if you expect to add 50 items to an array one at a time, you can call Allocate() first to allocate the required space. This will prevent the need for frequent reallocation.

Parameters

[in]	iSize	The new size for the array
[in]	bKeepContent	if true, the array contents will be preserved. Otherwise they will be discarded.

Definition at line 430 of file array.h.

          { if ( !bKeepContent ) Clear(); return Array<type>::Alloc( iSize ); };

bool Extend ( unsigned int  iIndex )

inline

Extends the logical size of the array.

Returns true if successful.

If the specified size is not larger than the current array, nothing will happen. Otherwise the logical size of the array will be extended to one more than the specified index. New memory will be allocated as necessary to hold the new items. Returns true if successful.

Parameters

[in]

iIndex

The array index to extend to. For example, if you specify 7, the new array will contain 8 elements (indexed 0 to 7).

Definition at line 440 of file array.h.

    { 
        if ( Array<type>::Extend( iIndex ) )
        {
            m_iSize = Max( m_iSize, iIndex+1 );
            return true;
        };
        return false;
    };

bool Extend ( int  iIndex )

inline

Extends the logical size of the array.

Returns true if successful.

If the specified size is not larger than the current array, nothing will happen. Otherwise the logical size of the array will be extended to one more than the specified index. New memory will be allocated as necessary to hold the new items. Returns true if successful.

Parameters

[in]

iIndex

The array index to extend to. For example, if you specify 7, the new array will contain 8 elements (indexed 0 to 7).

Definition at line 457 of file array.h.

          { return Extend( (unsigned int)iIndex ); };

void RemoveTail ( int  iItemCount = 1 )

inline

Removes the final items from the array.

Parameters

[in]

iItemCount

The number if items to remove from the end of the array

Definition at line 462 of file array.h.

          { SetItemCount( ItemCount()-iItemCount ); };

void Fill ( type  cPattern )

inline

Fills the array with a specified element.

Parameters

[in]

cPattern

The value to which every item in the array will be set

Definition at line 467 of file array.h.

          { for ( unsigned int i = 0; i < m_iSize; i++ ) operator[](i) = cPattern; };

void ByteFill ( unsigned char  cPattern )

inline

Fills the array with a specified byte pattern.

This method is similar to Fill, but it is much faster.

Parameters

[in]

cPattern

The value to which every item in the array will be set

Definition at line 473 of file array.h.

          { memset( Array<type>::m_pArray, (unsigned int)cPattern, sizeof(type) * m_iSize ); }

unsigned int Add ( const type &  e )

inline

Adds a new item to the array, increasing the array size by 1.

The index of the added element is returned.

If you plan to add a number of objects using this method, you can improve efficiency by preallocating all the space you will need using the Allocate() method.

Parameters

[in]

e

The element to be added to the end of the array

Definition at line 482 of file array.h.

          { if( Array<type>::Extend( m_iSize ) ) { Array<type>::operator[]( m_iSize ) = e; return m_iSize++; } else return 0xffffffff; };

unsigned int Add ( type &  e )

inline

Adds a new item to the array, increasing the array size by 1.

The index of the added element is returned.

If you plan to add a number of objects using this method, you can improve efficiency by preallocating all the space you will need using the Allocate() method.

Parameters

[in]

e

The element to be added to the end of the array

Definition at line 490 of file array.h.

          { if( Array<type>::Extend( m_iSize ) ) { Array<type>::operator[]( m_iSize ) = e; return m_iSize++; } else return 0xffffffff; };

Store& operator= ( const Store< type > &  s )

inline

Transfers the contents of another array to this one, leaving the original array empty.

If you want to copy the contents of the source array (instead of transferring it), use the Copy() or Clone() functions.

Definition at line 497 of file array.h.

{ m_iSize = s.m_iSize; s.m_iSize = 0; Array<type>::operator =( s ); return *this; };

void GetFrom ( Store< type > &  s )

inline

Transfers the contents of another array to this one, leaving the original array empty.

If you want to copy the contents of the source array (instead of transferring it), use the Copy() or Clone() functions.

Parameters

[in]

s

The array whose contents are to be transferred to this one

Definition at line 502 of file array.h.

          { m_iSize = s.m_iSize; Array<type>::operator =( s ); };

const type& operator[] ( unsigned int  iIndex ) const

inline

Returns an indexed item from the array.

Definition at line 507 of file array.h.

{ return Array<type>::m_pArray[iIndex]; };

type& operator[] ( unsigned int  iIndex )

inline

Returns an indexed item from the array.

Definition at line 510 of file array.h.

{ MB_ASSERT( iIndex < m_iSize ); return Array<type>::m_pArray[iIndex]; };

const type& operator[] ( int  iIndex ) const

inline

Returns an indexed item from the array.

Definition at line 513 of file array.h.

{ return operator[]( (unsigned int)iIndex ); };

type& operator[] ( int  iIndex )

inline

Returns an indexed item from the array.

Definition at line 516 of file array.h.

{ return operator[]( (unsigned int)iIndex ); };

bool IsEmpty ( void  ) const

inline

Returns true if the array has no items.

Definition at line 520 of file array.h.

{ return ItemCount() == 0; };

operator bool ( void  ) const

inline

Allows you to use the array as a boolean in if statements. Evaluates to true if the array is not empty.

Definition at line 523 of file array.h.

{ return !IsEmpty(); };

bool operator! ( void  ) const

inline

Evaluates to true if the array contains no items.

Definition at line 526 of file array.h.

{ return IsEmpty(); };

void SetBuffer ( type *  pData, unsigned int  iSize = 0  )

inline

Makes a Store array from a regular C or C++ array.

This method takes a pointer to a block of memory that contains a C-style array of elements of the appropriate type, and makes that into a Mudbox array object. Once this is called, the Store item will control the memory block, and extend or deallocate it as needed, as part of its own methods and destructor.

It is the responsibility of the caller to ensure that the source array is at least as big as the specified size.

Definition at line 537 of file array.h.

{ m_iSize = Array<type>::m_iSize = iSize; Array<type>::m_pArray = pData; };

void Serialize

(

class Stream &

s

)

Serializes the the array and its contents from/to a stream.

Parameters

[in]

s

The stream from/to which to read/write the array

Definition at line 294 of file stream.h.

{
    if ( !s.IsStoring() )
        SetItemCount( s.ReadInt() );
    else
        s << m_iSize;
    for ( unsigned int i = 0; i < m_iSize; i++ )
        s == operator[]( i );
};

void Sort ( void  )

inline

Sorts the items in the array.

This method will sort all the items in the array from least to greatest. If the array is of a non-numeric or non-string type, this method determines the relative ordering of items using the subtraction ("-") operator. In order to use this method, you must ensure that the subtraction operator is defined for the data type stored in this array, with these properties:

if A is less than B, then A-B must return a negative integer

if A is greater than B, then A-B must return a positive integer

if A is equivalent to B, then A-B must return 0

Definition at line 556 of file array.h.

{ QuickSort( Array<type>::m_pArray, m_iSize, sizeof(type), Compare ); };

type* Find ( type  a )

inline

Returns a pointer to the item in the array with a particular value.

The array must be sorted before using this call.

This method uses a binary search to return a pointer to an element in the array with the specified value. If the value is not found, then NULL is returned. Before this method can be called, the array must be sorted (by calling the Sort() method).

Note: The pointer returned by this function should not be kept for later use, as the contents of an array can move around in memory as items are added and removed. It should only be used immediately.

Parameters

[in]

a

The value to search for in the array

Definition at line 566 of file array.h.

          { return (type *) bsearch( &a, Array<type>::m_pArray, m_iSize, sizeof(type), Compare ); };

type* Find ( type *  a )

inline

Returns a pointer to the item in the array with a particular value.

The array must be sorted before using this call.

This method uses a binary search to return a pointer to an element in the array with the specified value. If the value is not found, then NULL is returned. Before this method can be called, the array must be sorted (by calling the Sort() method).

Note: The pointer returned by this function should not be kept for later use, as the contents of an array can move around in memory as items are added and removed. It should only be used immediately.

Definition at line 578 of file array.h.

{ return (type *) bsearch( a, Array<type>::m_pArray, m_iSize, sizeof(type), Compare ); };

unsigned int IndexOf ( type  pValue )

inline

Returns the first index of the element equal to pValue.

Note this method requires that operator == be defined for the type of data stored in the array. Returns the index of the first occurance of pValue or 0xffffffff if the array does not contain pValue.

Definition at line 584 of file array.h.

    {
        for(unsigned int i = 0; i < ItemCount(); ++i )
            if( (*this)[i] == pValue )
                return i;
        return 0xffffffff;
    };

unsigned int Remove ( const type &  e )

inline

Remove every occurrence of a specified item from the array. Returns the number of removed items.

Parameters

[in]

e

the item to remove from the array

Definition at line 593 of file array.h.

    {
        unsigned int j = 0, i = 0;
        while ( i < ItemCount() )
        {
            if ( operator[]( i ) != e )
                operator[]( j++ ) = operator[]( i );
            i++;
        };
        SetItemCount( j );
        return i-j;
    };

void RemoveAt ( unsigned int  iIndex )

inline

Removes the item at the specified index from the array.

Parameters

[in]

iIndex

index of the item to be removed

Definition at line 609 of file array.h.

    {
        while ( iIndex+1 < ItemCount( ) )
        {
            operator[]( iIndex ) = operator[]( iIndex+1 );
            iIndex++;
        };
        SetItemCount( Min(iIndex,ItemCount()-1) );
    };

unsigned int RemoveDuplicates ( void  )

inline

Removes duplicated items from the array after sorting it.

See the Sort() method for information on what makes an array Sort-able. This method sorts the contents of the array, then goes through and removes any duplicate entries, leaving a list of unique items. It returns the number of items that were removed.

Definition at line 627 of file array.h.

    {
        if ( ItemCount() == 0 )
            return 0;
        Sort();
        unsigned int j = 0;
        for ( unsigned int i = 0; i < ItemCount()-1; i++ )
        {
            if ( operator[]( i ) != operator[]( i+1 ) )
                operator[]( j++ ) = operator[]( i );
        };
        operator[]( j++ ) = operator[]( ItemCount()-1 );
        unsigned iRemoved = ItemCount()-j;
        m_iSize = j;
        return iRemoved;
    };

unsigned int ItemCount ( void  ) const

inline

Returns the number of items in the array.

Definition at line 645 of file array.h.

{ return m_iSize; };

type& Last ( void  )

inline

Returns the last item in the array, or 0 if the array is empty.

Definition at line 648 of file array.h.

{ if ( ItemCount() ) return operator []( ItemCount()-1 ); else throw new Error( "Store::LastItem called for an empty store" ); };

void Optimize ( void  )

inline

Reduces the allocated memory size to match the size of the current elements in the array.

Arrays derived from Store automatically grow their memory as needed to accommodate the items that are added to them. For efficiency, when an array expands it allocates more memory than it immediately needs. This reduces the number of expensive memory allocations.

The Optimize methods allocates a new block of memory, precisely the size needed to hold the current contents of the array, then copies the array data to this new block before deleting the existing block. Use it to minimize the memory footprint of arrays that are unlikely to expand, but that you need to keep around.

Definition at line 659 of file array.h.

{ Array<type>::Alloc( m_iSize ); };

static int Compare ( const void *  a, const void *  b  )

inlinestaticprotected

Definition at line 662 of file array.h.

{ return (int)(*((type *)a)-*((type *)b)); };

Member Data Documentation

unsigned int m_iSize

mutable

Definition at line 677 of file array.h.

---

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

• Mudbox/array.h
• Mudbox/stream.h