vtArray< E > Class Template Reference

Public Member Functions
	vtArray (uint size=0)
	vtArray (const vtArray< E > &)
virtual	~vtArray ()
uint	GetSize () const
uint	GetMaxSize () const
bool	SetSize (uint)
bool	SetMaxSize (uint)
uint	GetElemSize () const
E *	GetData () const
void	FreeData ()
bool	IsEmpty () const
E &	GetAt (uint i) const
bool	SetAt (uint i, E)
vtArray< E > &	operator= (const vtArray< E > &)
E &	operator[] (uint i)
const E &	operator[] (uint i) const
void	Clear ()
bool	RemoveAt (uint i, int n=1)
int	Append (const E &)
int	Append (const vtArray< E > &)
int	Find (const E &) const

Protected Member Functions
virtual bool	Grow (uint)
virtual void	DestructItems (uint first, uint last)

Protected Attributes
uint	m_Size
uint	m_MaxSize
E *	m_Data

Detailed Description

template<class E>
class vtArray< E >

An Array template which automatically grows as you add or set entities.

Note that construction and destruction is not done automatically if the entities are class objects. You can provide this destruction yourself by overriding the DestructItems method, but it is easier to use this template for objects with simple value semantics such as basic types (int, float..), structs, and pointers. If you do create a subclass like this:

class MyArray : public vtArray<MyObject *> {};

note that you will need to provide not only a DestructItems() implementation, but also a destructor. This is because the default vtArray destructor is not smart enough to call your DestructItems() method (it will call the base DestructItems() instead, which does nothing).

A full working example is:

class MyArray : public vtArray<MyObject *>
{
    virtual ~MyArray() { Clear(); free(m_Data); m_Data = NULL; m_MaxSize = 0; }
    virtual void DestructItems(uint first, uint last)
    {
        for (uint i = first; i <= last; i++)
            delete GetAt(i);
    }
};

Constructor & Destructor Documentation

template<class E >

vtArray< E >::vtArray

(

uint

size = 0

)

Creates and initializes an empty array (array with no elements).

Parameters

size	number of elements data area should initially make room for (initial value of [MaxSize]). If zero, little initial space is allocated but the array will grow dynamically as space is needed.

See also

vtArray::SetMaxSize vtArray::SetSize

Example:

vtArray<void*> foo;     // empty array of pointers

template<class E>

vtArray< E >::vtArray

(

const vtArray< E > &

a

)

Creates and initializes an array from another (of the same type).

Parameters

a	An array to copy from.

template<class E >

vtArray< E >::~vtArray ( )

inlinevirtual

Destructor for array class.

Member Function Documentation

template<class E>

int vtArray< E >::Append ( const E &  v )

inline

Appends one element onto the end of the array. If the array is dynamically managed, it is enlarged to accomodate another element if necessary.

Parameters

<v>	value of the new element

Returns

void* -> element added (within array) or NULL if out of memory

See also

vtArray::SetAt vtArray::SetSize vtArray::RemoveAt

Examples:

vtArray<float>  vals;
vals.Append(1.0f);    // first element
vals.Append(2.0f);    // second element
vals.SetAt(5, 6.0f);  // sixth element
vals.Append(7.0f);    // seventh element

template<class E>

int vtArray< E >::Append

(

const vtArray< E > &

src

)

Concatenates the contents of the source array into the destination array. The destination array is enlarged if possible. When an object array is appended, the objects are multiply referenced (not duplicated).

Parameters

<src>

Source array containing elements to be appended

Returns

index of last element successfully added or -1 on error

See also

vtArray::Append vtArray::SetAt

Examples:

int zap[3] = { 1, 2, 3 };
vtArray<int> zip(3, &zap);  // user managed
vtArray<int> zot;               // dynamic
zot.Append(zip);            // adds 1 2 3
zot.Append(zip);            // adds 1 2 3 again

template<class E >

void vtArray< E >::Clear

(

)

Removes the elements in the array but not the array data area. An array is considered empty if it has no elements.

See also

vtArray::SetSize vtArray::IsEmpty

template<class E >

void vtArray< E >::DestructItems ( uint  first, uint  last  )

inlineprotectedvirtual

Called by the array implementation when array items are deleted. The default implementation does not call the destructors for the array items. This will not work if your array elements do memory deallocation in their destructors.

Override this function to explicitly call the destructors properly if you need this functionality.

Parameters

first	Index of first element to destroy
last	Index of last element to destroy

Example:

// Overrides DestructItems to call constructors
inline void MyArray::DestructItems(uint first, uint last)
{
    for (uint i = first; i <= last; ++i)
       delete GetAt(i);
}

template<class E>

int vtArray< E >::Find

(

const E &

elem

)

const

Compares each element of the array to the input element and returns the index of the first one that matches. Comparison of elements is done using operator== (which must be defined for your element class if you want to use Find).

Parameters

<elem>

value of the element to match

Returns

int index of matching array element or -1 if not found

See also

vtArray::SetAt

Examples:

vtArray<int> foo;        // define integer array
foo.Append(5);       // first element is 5
foo.Append(6);       // second element is 5
int t = foo.Find(7);  // returns -1
t = foo.Find(6);      // returns 1

template<class E >

void vtArray< E >::FreeData

(

)

Complete free the data held by this array's data.

template<class E >

E & vtArray< E >::GetAt ( uint  i ) const

inline

Gets the i'th element of the array.

Parameters

i	0 based index of element to get. Like C++ arrays, these arrays do not check the range of the index so your program will crash if you supply a number less than zero or greater than the array size as an index.

Returns

element accessed

template<class E >

bool vtArray< E >::Grow ( uint  growto )

protectedvirtual

Enlarge the array to accomodate growto elements. If the array can already hold this many elements, nothing is done. Otherwise, the data area of the array is enlarged (reallocating if necessary) so that growto contiguous elements can be stored.

Parameters

growto

Number of elements the array should be able to hold after it has grown

Returns

True if array was successfully grown, else false.

See also

vtArray::SetData vtArray::SetMaxSize

template<class E >

bool vtArray< E >::IsEmpty ( ) const

inline

Determines whether an array has elements or not

Returns

True if array contains no elements, else false.

See also

vtArray::SetSize vtArray::Empty

template<class E >

bool vtArray< E >::RemoveAt	(	uint	i,
		int	n = 1
	)

Removes the i'th element of the array. The following elements are shuffled up to eliminate the unused space.

Parameters

i	Index of element to remove (0 based)
n	Number of elements to remove (default 1)

Returns

bool True if element was successfully removed, else false.

See also

vtArray::Append vtArray::SetAt vtArray::SetSize

Examples:

vtArray<int16> zot(8); // room for 8 shorts
zot.SetSize(8);      // now has 8 zeros
zot[1] = 1;          // second element
zot[2] = 2;          // third element
zot.RemoveAt(0);     // remove first element
zot.RemoveAt(-1);    // returns false

template<class E>

bool vtArray< E >::SetAt	(	uint	i,
		E	val
	)

Sets the i'th element of the array to the given value. The number of bytes copied is determined by the element size of the array specified at initialization time. If the array is not large enough, it is extended to become 1 1/2 times its current size.

Parameters

i	Index of new element (0 based)
val	Value of the new element.

Returns

int index of element added or -1 if out of memory

Examples:

vtArray<RGBi> cols(16);         // room for 16 colors
cols.SetAt(0, RGBi(1,1,1));     // first color white
cols.SetAt(15, RGBi(1,0,0));    // last color red
                                // makes Colors 1-14, too
cols.SetAt(17, RGBi(0,1,1));    // causes array growth

template<class E >

bool vtArray< E >::SetMaxSize

(

uint

s

)

If the array is user-managed, MaxSize establishes the maximum number of elements that can be stored. If the array is dynamically managed by the system, setting the maximum size enlarges its data area to accomodate the required number of elements.

Parameters

s	Current maximum size of array (number of elements its data area can hold)

Returns

bool, true if maximum size successfully changed, else false.

See also

vtArray::SetData vtArray::SetSize vtArray::GetElemSize vtArray::Grow

template<class E >

bool vtArray< E >::SetSize ( uint  s )

inline

Set the current array size. If the array is dynamically managed, it will be enlarged to accomodate the new size. If not, the array size cannot be set beyond the current maximum size. When the array size is enlarged, we should call constructors for the new empty elements. We don't do that yet.

Parameters

s	Current number of elements contained in array

Returns

bool True if size successfully changed, else false.

See also

vtArray::SetData vtArray::Grow vtArray::SetMaxSize

Examples:

vtArray<RGBi> cols(256);      // room for 256 colors
int ncols = cols.GetSize(); // will be zero
ncols = cols.GetMaxSize();  // will be 256
cols.SetSize(ncols);        // calls 256 Color4 constructors NOT