This reference page is linked to from the following overview topics: Logging and Debugging Functions, Miscellaneous Utilities.

Detailed 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:: MeshDisplace/displacer.h, and PLYImport/Importer.cpp.

Definition at line 298 of file array.h.

#include <array.h>

Inheritance diagram for Store< type >:

[legend]

List of all members.

Public Member Functions
	Store (const char *sName="unknown")
	Creates an empty array.
	Store (unsigned int iSize, const char *sName)
	Creates an array with space for some elements already allocated.
	Store (const type pArray, int iSize, const char sName="unknown")
	Creates an array and populates it will information copied from another array.
	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.
	Store (const Store &s)
	Creates an array from another one. The other array becomes empty after the operation.
	~Store (void)
	Destroys the contents of the array and deallocate its memory.
bool	Copy (Store &s) const
	Copies the contents of another array into this one, duplicating all data. Returns true if successful.
Store	Clone (void) const
	Returns a copy of this array. The returned copy will have a duplicate of all data in the original.
void	Clone (Store &s) const
	Copies the contents of another array into this one, duplicating all data.
void	Clear (bool bDestruct=false)
	Clears the array and deallocates its memory.
bool	SetItemCount (unsigned int iSize, bool bKeepContent=false)
	Sets the logical size of the array.
bool	Allocate (unsigned int iSize, bool bKeepContent=false)
	Preallocates memory for the an array, without changing the array's logical size.
bool	Extend (unsigned int iIndex)
	Extends the logical size of the array.
bool	Extend (int iIndex)
	Extends the logical size of the array.
void	RemoveTail (int iItemCount=1)
	Removes the final items from the array.
void	Fill (type cPattern)
	Fills the array with a specified element.
unsigned int	Add (const type &e)
	Adds a new item to the array, increasing the array size by 1.
unsigned int	Add (type &e)
	Adds a new item to the array, increasing the array size by 1.
Store &	operator= (const Store &s)
	Transfers the contents of another array to this one, leaving the original array empty.
void	GetFrom (Store &s)
	Transfers the contents of another array to this one, leaving the original array empty.
const type &	operator[] (unsigned int iIndex) const
	Returns an indexed item from the array.
type &	operator[] (unsigned int iIndex)
	Returns an indexed item from the array.
const type &	operator[] (int iIndex) const
	Returns an indexed item from the array.
type &	operator[] (int iIndex)
	Returns an indexed item from the array.
type *	operator+ (unsigned int iIndex)
	Returns a pointer to an item in the array.
type *	operator+ (int iIndex)
	Returns a pointer to an item in the array.
bool	IsEmpty (void) const
	Returns true if the array has no items.
	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.
bool	operator! (void) const
	Evaluates to true if the array contains no items.
void	SetBuffer (type *pData, unsigned int iSize=0)
	Makes a Store array from a regular C or C++ array.
void	Serialize (class Stream &s)
	Serializes the the array and its contents from/to a stream.
void	Sort (void)
	Sorts the items in the array.
type *	Find (type a)
	Returns a pointer to the item in the array with a particular value.
type *	Find (type *a)
	Returns a pointer to the item in the array with a particular value.
unsigned int	IndexOf (type pValue)
	Returns the first index of the element equal to pValue.
unsigned int	Remove (const type &e)
	Remove every occurrence of a specified item from the array. Returns the number of removed items.
void	Remove (unsigned int iIndex)
	Removes the item at the specified index from the array.
unsigned int	RemoveDuplicates (void)
	Removes duplicated items from the array after sorting it.
unsigned int	ItemCount (void) const
	Returns the number of items in the array.
type &	Last (void)
	Returns the last item in the array, or 0 if the array is empty.
void	Optimize (void)
	Reduces the allocated memory size to match the size of the current elements in the array.
Public Attributes
unsigned int	m_iSize
Static Protected Member Functions
static int	Compare (const void a, const void b)

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 302 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 314 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 324 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 331 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 337 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 342 of file array.h.

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

Member Function Documentation

bool Copy ( Store< type > & s ) const [inline]

bool SetItemCount	(	unsigned int	iSize,
		bool	bKeepContent = `false`
	)		`[inline]`

[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.

bool Allocate	(	unsigned int	iSize,
		bool	bKeepContent = `false`
	)		`[inline]`

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

void SetBuffer	(	type *	pData,
		unsigned int	iSize = `0`
	)		`[inline]`

static int Compare	(	const void *	a,
		const void *	b
	)		`[inline, static, protected]`

Store< type > Class Template Reference

Detailed Description

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

Public Member Functions

Public Attributes

Static Protected Member Functions

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

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