- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files
- Directories
- Examples

- Class List
- Class Hierarchy
- Class Members

Public Member Functions | Public Attributes | Static Protected Member Functions

# Store< type > Class Template Reference

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

Search for all occurrences

## 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 299 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 | RemoveAt (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 303 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 315 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 325 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 332 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 338 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 343 of file array.h.

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

## Member Function Documentation

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

Search for all occurrences

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 346 of file array.h.

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

Store Clone | ( | void |  | ) | const `[inline]`

Search for all occurrences

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

Reimplemented from Array< type >.

Definition at line 351 of file array.h.

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

void Clone | ( | Store< type > & | s | ) | const `[inline]`

Search for all occurrences

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

Parameters:

  [in] | s | The array to be duplicated

Definition at line 354 of file array.h.

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

void Clear | ( | bool | bDestruct = `false` | ) | `[inline]`

Search for all occurrences

Clears the array and deallocates its memory.

Parameters:

  [in] | bDestruct | If true, the destructor will be called for each element.

Reimplemented from Array< type >.

Definition at line 359 of file array.h.

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

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

Search for all occurrences

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 368 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]`

Search for all occurrences

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 393 of file array.h.

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

bool Extend | ( | unsigned int | iIndex | ) | `[inline]`

Search for all occurrences

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

Reimplemented from Array< type >.

Definition at line 403 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]`

Search for all occurrences

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 420 of file array.h.

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

void RemoveTail | ( | int | iItemCount = `1` | ) | `[inline]`

Search for all occurrences

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 425 of file array.h.

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

void Fill | ( | type | cPattern | ) | `[inline]`

Search for all occurrences

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 430 of file array.h.

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

unsigned int Add | ( | const type & | e | ) | `[inline]`

Search for all occurrences

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 438 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]`

Search for all occurrences

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 446 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 453 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]`

Search for all occurrences

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

Reimplemented from Array< type >.

Definition at line 463 of file array.h.

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

type& operator[] | ( | unsigned int | iIndex | ) | `[inline]`

Returns an indexed item from the array.

Reimplemented from Array< type >.

Definition at line 466 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 469 of file array.h.

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

type& operator[] | ( | int | iIndex | ) | `[inline]`

Returns an indexed item from the array.

Reimplemented from Array< type >.

Definition at line 472 of file array.h.

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

type* operator+ | ( | unsigned int | iIndex | ) | `[inline]`

Returns a pointer to an item in the array.

THIS FUNCTION IS UNSAFE.

This method allows you to access the address of an array element. However, since many basic array operations can change the memory location of items in the array, this pointer should only be referenced immediately, and never kept around.

Reimplemented from Array< type >.

Definition at line 479 of file array.h.

    { return &operator[]( iIndex ); };

type* operator+ | ( | int | iIndex | ) | `[inline]`

Returns a pointer to an item in the array.

THIS FUNCTION IS UNSAFE.

This method allows you to access the address of an array element. However, since many basic array operations can change the memory location of items in the array, this pointer should only be referenced immediately, and never kept around.

Reimplemented from Array< type >.

Definition at line 486 of file array.h.

    { return &operator[]( iIndex ); };

bool IsEmpty | ( | void |  | ) | const `[inline]`

Search for all occurrences

Returns true if the array has no items.

Definition at line 489 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 492 of file array.h.

    { return !IsEmpty(); };

bool operator! | ( | void |  | ) | const `[inline]`

Evaluates to true if the array contains no items.

Definition at line 495 of file array.h.

    { return IsEmpty(); };

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

Search for all occurrences

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 506 of file array.h.

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

void Serialize | ( | class Stream & | s | ) |

Search for all occurrences

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 290 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]`

Search for all occurrences

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 525 of file array.h.

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

type* Find | ( | type | a | ) | `[inline]`

Search for all occurrences

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 535 of file array.h.

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

type* Find | ( | type * | a | ) | `[inline]`

Search for all occurrences

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 547 of file array.h.

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

unsigned int IndexOf | ( | type | pValue | ) | `[inline]`

Search for all occurrences

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 553 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]`

Search for all occurrences

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 562 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]`

Search for all occurrences

Removes the item at the specified index from the array.

Parameters:

  [in] | iIndex | index of the item to be removed

Definition at line 578 of file array.h.

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

unsigned int RemoveDuplicates | ( | void |  | ) | `[inline]`

Search for all occurrences

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 596 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]`

Search for all occurrences

Returns the number of items in the array.

Definition at line 614 of file array.h.

    { return m_iSize; };

type& Last | ( | void |  | ) | `[inline]`

Search for all occurrences

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

Definition at line 617 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]`

Search for all occurrences

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 628 of file array.h.

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

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

Search for all occurrences

Definition at line 631 of file array.h.

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

## Member Data Documentation

unsigned int m_iSize `[mutable]`

Search for all occurrences

Reimplemented from Array< type >.

Definition at line 631 of file array.h.

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

- Mudbox/array.h
- Mudbox/stream.h