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  )

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 (   )  [inline, virtual]

Destructor for array class.

---

Member Function Documentation

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

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

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

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 )

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  )

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

---