CascadeArray Class Reference

an easy-to-use array class with automatic memory management More...

#include <cascade/util/CascadeArray.h>

Inheritance diagram for CascadeArray:

List of all members.


Public Types
typedef int()	ArraySortFunction (const void inItem1, const void inItem2)
Public Member Functions
	CascadeArray (u32 inItemSize, u32 inDesiredItemCount=0)
virtual	~CascadeArray ()
	destructor
u32	Count () const
virtual bool	Append (void *inItem, u32 &outIndex)
virtual bool	Insert (void *inItem, u32 &ioIndex)
virtual bool	Remove (void *inItemToRemove)
bool	RemoveAtIndex (u32 inIndex)
void	Empty (void)
bool	Swap (u32 inIndex1, u32 inIndex2)
bool	AdjustAllocation (u32 inDesiredItemCount)
	true if both items were found and swapped, false otherwise
void	TrimAllocation (void)
virtual bool	FetchItem (u32 inIndex, void *outItem) const
virtual void	Sort (ArraySortFunction *inFunction)
Protected Attributes
u32	mItemSize
u32	mArraySize
u32	mCount
void *	mData

Detailed Description

an easy-to-use array class with automatic memory management

Skip the description

Implements an array of aribtrary-sized (but uniformly-sized within a single array) objects in a contiguous memory buffer. Access and append operations are fast. Insertion and removal may require moving other array items in memory. For faster insert/removal/sort and somewhat slower access, consider CascadeList [not yet implemented].

Memory allocation for array storage is automatic, using a strategy of doubling the array size when it needs to grow. The AdjustAllocation() function is provided for instances where the approximate number of items is known in advance of inserting items. TrimAllocation() can also be called to compact the allocated memory to house only items currently in the array, when further additions to the array are not anticipated.

Warning:: Insertion and retrieval copy memory. Do not insert objects or structures which contain self-referential absolute memory addresses. (But you wouldn't build such a thing anyway, right?) Consider inserting pointers to large objects/structures rather than the items themselves for improved performance.

Note:: CascadeTemplateArray may be more convenient syntactically, and should also be safer given that it deals in object references rather than void pointers

class CascadeArray

Member Typedef Documentation

typedef int() CascadeArray::ArraySortFunction(const void *inItem1, const void *inItem2)

sorting comparison function prototype
The Sort function must be passed a comparison function suitable for comparing the type of data in the array. This is the prototype.

Parameters:

inItem1 The first item to compare

inItem2 The second item to compare

Returns:
0 if items are equal. Less than zero if inItem1 is "less than" inItem2. Greater than zero if inItem2 is "greater than" inItem1.

Constructor & Destructor Documentation

CascadeArray::CascadeArray ( u32 inItemSize,

u32 inDesiredItemCount = 0

)

constructor
Constructs an array of items of size inItemSize
Parameters:

inItemSize the size (in bytes) of the individual items to be stored in the array (best to use sizeof).

inDesiredItemCount (optional) allows the constructor to allocate internal storage of the correct size if the number of items is known in advance.

virtual CascadeArray::~CascadeArray ( ) [virtual]

destructor

Member Function Documentation

bool CascadeArray::AdjustAllocation ( u32 inDesiredItemCount )

true if both items were found and swapped, false otherwise
re-size internal storage
Re-sizes the array's internal storage. This function may be called if the approximate size of the array is known, to avoid multiple resizings as items are added. May fail if memory allocation fails.

Note:
This function is inexpensive if the array is of sufficient size already.

Parameters:

inDesiredItemCount the desired size of the array

Returns:
true if adjustment succeeded, false if memory allocation failed.

virtual bool CascadeArray::Append ( void * inItem,

u32 & outIndex

) [virtual]

append an item to the array
Append the supplied item to the array. This may fail because memory may have to be allocated to hold the new item. The index of the newly-appended item is returned in the outIndex parameter if the append was successful
Note:
the contents of inItem are copied into the array

Parameters:

inItem the item to be appended

outIndex the index at which the item was appended (only if return value of function is true)

Returns:
true if successful, false if failure

Reimplemented in CascadeTemplateArray< T >, CascadeTemplateArray< Vessel * >, CascadeTemplateArray< TimerEntry >, CascadeTemplateArray< VideoStream >, CascadeTemplateArray< CascadeFSObject * >, CascadeTemplateArray< AudioStream >, CascadeTemplateArray< RepaintEntry >, CascadeTemplateArray< char * >, CascadeTemplateArray< CascadeAppMessageSink * >, and CascadeTemplateArray< ProgramRecord * >.

u32 CascadeArray::Count ( ) const [inline]

void CascadeArray::Empty ( void ) [inline]

empty the array
Makes the array empty.
Note:
This function does not adjust the array's allocation.
If the array contains object pointers, this function does NOT delete the contained elements. Callers should loop over the array and delete all items first.

virtual bool CascadeArray::FetchItem ( u32 inIndex,

void * outItem

) const [virtual]

return a copy of the item at index
Returns a copy of the item at the supplied index. May fail if the index is invalid

Parameters:

inIndex the index of the item to fetch

outItem the destination pointer (caller must insure that the pointer is of adequate size)

Returns:
true if successful, false if invalid index

Reimplemented in CascadeTemplateArray< T >, CascadeTemplateArray< Vessel * >, CascadeTemplateArray< TimerEntry >, CascadeTemplateArray< VideoStream >, CascadeTemplateArray< CascadeFSObject * >, CascadeTemplateArray< AudioStream >, CascadeTemplateArray< RepaintEntry >, CascadeTemplateArray< char * >, CascadeTemplateArray< CascadeAppMessageSink * >, and CascadeTemplateArray< ProgramRecord * >.

virtual bool CascadeArray::Insert ( void * inItem,

u32 & ioIndex

) [virtual]

insert an item into the array
Insert the supplied item into the array. This may fail because memory may have to be allocated to hold the new item. The index of the newly-inserted item is returned in the ioIndex parameter if the insertion was successful
Note:
the contents of inItem are copied into the array

Parameters:

inItem the item to be inserted

ioIndex on entry, the index at which you wish to insert. If successful, on exit is the index at which the item was actually inserted (may differ if the supplied index was out of range)

Returns:
true if successful, false if failure

Reimplemented in CascadeTemplateArray< T >, CascadeTemplateArray< Vessel * >, CascadeTemplateArray< TimerEntry >, CascadeTemplateArray< VideoStream >, CascadeTemplateArray< CascadeFSObject * >, CascadeTemplateArray< AudioStream >, CascadeTemplateArray< RepaintEntry >, CascadeTemplateArray< char * >, CascadeTemplateArray< CascadeAppMessageSink * >, and CascadeTemplateArray< ProgramRecord * >.

bool CascadeArray::RemoveAtIndex ( u32 inIndex )

remove an item
Removes the item at the given index from the array. If the index is invalid, nothing happens and this function returns false
Parameters:

inIndex the index of the item to remove

Returns:
true if item was found and removed, false if index invalid

virtual void CascadeArray::Sort ( ArraySortFunction * inFunction ) [virtual]

sort the array
Sort sorts the contents of the array using a QuickSort, using the supplied function to compare items.

Parameters:

inFunction the comparison function to use for the sort

bool CascadeArray::Swap ( u32 inIndex1,

u32 inIndex2

)

swaps two items
Swaps the position of two items in the array if both supplied indexes are valid.
Parameters:

inIndex1 the index of the first item to swap

void CascadeArray::TrimAllocation ( void )

re-size array's internal storage to fit contained items
Re-sizes the array's internal storage to fit items already in the array. (Future insertions or appends will cause the memory to grow again.)