vtArray< E > Class Template Reference

List of all members.

Public Member Functions
	vtArray (unsigned int size=0)
	vtArray (const vtArray< E > &)
virtual	~vtArray ()
unsigned int	GetSize () const
unsigned int	GetMaxSize () const
bool	SetSize (unsigned int)
bool	SetMaxSize (unsigned int)
unsigned int	GetElemSize () const
E *	GetData () const
bool	IsEmpty () const
E &	GetAt (unsigned int i) const
bool	SetAt (unsigned int i, E)
vtArray< E > &	operator= (const vtArray< E > &)
E &	operator[] (unsigned int i)
const E &	operator[] (unsigned int i) const
void	Empty ()
bool	RemoveAt (unsigned int i, int n=1)
int	Append (const E &)
int	Append (const vtArray< E > &)
int	Find (const E &) const
Protected Member Functions
virtual bool	Grow (unsigned int)
virtual void	DestructItems (unsigned int first, unsigned int last)
Protected Attributes
unsigned int	m_Size
unsigned int	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() { Empty(); free(m_Data); m_Data = NULL; m_MaxSize = 0; }
        virtual void DestructItems(unsigned int first, unsigned int last)
        {
            for (unsigned int i = first; i <= last; i++)
                delete GetAt(i);
        }
    };

---

Constructor & Destructor Documentation

template<class E >

vtArray< E >::vtArray

(

unsigned int

size = 0

)

[inline]

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

)

[inline]

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

Parameters:

a

An array to copy from.

template<class E >

vtArray< E >::~vtArray

(

)

[inline, virtual]

Destructor for array class.

---

Member Function Documentation

template<class E >

int vtArray< E >::Append

(

const vtArray< E > &

src

)

[inline]

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 >

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 >

void vtArray< E >::DestructItems	(	unsigned int	first,
		unsigned int	last
	)			[inline, protected, virtual]

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(unsigned int first, unsigned int last)
    {
        for (unsigned int i = first; i <= last; ++i)
           delete GetAt(i);
    }

template<class E >

void vtArray< E >::Empty

(

)

[inline]

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 >

int vtArray< E >::Find

(

const E &

elem

)

const [inline]

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 >

E & vtArray< E >::GetAt

(

unsigned int

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

(

unsigned int

growto

)

[inline, protected, virtual]

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	(	unsigned int	i,
		int	n = 1
	)			[inline]

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	(	unsigned int	i,
		E	val
	)			[inline]

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

(

unsigned int

s

)

[inline]

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

(

unsigned int

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