vtdata library
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
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
sizenumber 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
aAn 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:
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
firstIndex of first element to destroy
lastIndex 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
i0 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
growtoNumber 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
iIndex of element to remove (0 based)
nNumber 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,
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
iIndex of new element (0 based)
valValue 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
sCurrent 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
sCurrent 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