Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Class Members | File Members

BasicArray< T > Class Template Reference

A generic implementation of a dynamically allocated array. More...

#include <BasicArray.h>

Collaboration diagram for BasicArray< T >:

Collaboration graph
[legend]
List of all members.

Public Member Functions

 BasicArray (unsigned int initialCapacity=0)
 Create an empty array.
 ~BasicArray ()
 Destruct the array and all the data in it.
bool isEmpty () const
unsigned int getSize () const
void setSize (const unsigned int size)
 setSize() will increase the array capacity if the new size is larger than the current capacity.
unsigned int getCapacity () const
 Will always be >= to getSize().
T * getBuffer ()
 Modifying or deallocating this buffer may adversely effect the contents of the array.
T * adopt ()
 Release the internal buffer.
void reset (unsigned int initialCapacity=0)
 Set size to zero and deallocate memory.
void clear ()
 Set size to zero.
void increase (const unsigned int minCapacity, const unsigned int multiple=2)
 Increase array capacity if minCapacity is greater than the current capacity.
void shrink ()
 Calling this function assures that the array capacity is equal to its size by releasing any extra allocated memory.
unsigned int put (const T &x)
 Add the array element to the end of the array.
void put (const unsigned int i, const T &x)
 Add an array element.
unsigned int put (const T *x, const int count)
 Add an array of elements to the end of the array.
void put (const unsigned int i, const T *x, const int count)
 Add an array of elements to the array.
void * alloc (const unsigned int count)
 Allocate space for.
void * alloc (const unsigned int i, const unsigned int count)
 Allocate space for.
T & get (const unsigned int i) const
 If the index is out of range a BasicException will be thrown.
T & operator[] (const unsigned int i) const
 Allows you to access a BasicArray like a normal array.

Private Attributes

unsigned int capacity
unsigned int size
T * data

Detailed Description

template<class T>
class BasicArray< T >

A generic implementation of a dynamically allocated array.

WARNING class constructors and destructors are not called. Allocated memory is initially set to zero. This works well with arrays of pointers or basic data types, but will not work for classes such as std::string which requires the constructor be called.


Constructor & Destructor Documentation

template<class T>
BasicArray< T >::BasicArray unsigned int  initialCapacity = 0  )  [inline]
 

Create an empty array.

Parameters:
initialCapacity Initially allocate this many spaces.

template<class T>
BasicArray< T >::~BasicArray  )  [inline]
 

Destruct the array and all the data in it.


Member Function Documentation

template<class T>
T* BasicArray< T >::adopt  )  [inline]
 

Release the internal buffer.

It is then the callers responsibility to deallocate the returned pointer if not NULL.

Returns:
A pointer to the internal buffer.

template<class T>
void* BasicArray< T >::alloc const unsigned int  i,
const unsigned int  count
[inline]
 

Allocate space for.

Parameters:
count elements at position
i. This space may all ready be occupied by other array elements and writing to this memory may destroy their contents. If
i +
count is geater than the array size then the array size will be increased. You should normally use the put and get methods to access the array contents.
Returns:
A void * to the newly allocated memory.

template<class T>
void* BasicArray< T >::alloc const unsigned int  count  )  [inline]
 

Allocate space for.

Parameters:
count elements at the end of the array.
See also:
alloc(const unsigned int, const unsigned int).
Returns:
A void * to the newly allocated memory.

template<class T>
void BasicArray< T >::clear  )  [inline]
 

Set size to zero.

Does not effect capacity. Memory is not initialized to zero!

template<class T>
T& BasicArray< T >::get const unsigned int  i  )  const [inline]
 

If the index is out of range a BasicException will be thrown.

Array indexing starts from zero.

Parameters:
i The index of the array element.
Returns:
A reference to the array element at index i.

template<class T>
T* BasicArray< T >::getBuffer  )  [inline]
 

Modifying or deallocating this buffer may adversely effect the contents of the array.

Returns:
A pointer to the internal buffer.

template<class T>
unsigned int BasicArray< T >::getCapacity  )  const [inline]
 

Will always be >= to getSize().

Returns:
The number of slots currently allocated.

template<class T>
unsigned int BasicArray< T >::getSize  )  const [inline]
 

Returns:
The current size of the array.

template<class T>
void BasicArray< T >::increase const unsigned int  minCapacity,
const unsigned int  multiple = 2
[inline]
 

Increase array capacity if minCapacity is greater than the current capacity.

The capacity will be increased to the larger of minCapacity or multiple times the current capacity. The default value for multiple is 2.0. The advantage of this liberal memory allocation comes from the unfortunate side effect that when a memory block is reallocated it may be copied to a new location. Doubling the capacity reduces the amortized time complexity of adding n elements one at a time from O(n^2) to O(n*log(n)). The disadvantage is that up to twice as much memory may be used. If you know the maximum size of the array ahead of time you can set the capacity to that size in the constructor. You may also pass a multiple of zero causing increase to allocate no more than minCapacity.

If memory allocation fails when capacity is greater than minCapacity then allocation is retried with capacity equal to minCapacity. If allocation fails again an std::bad_alloc() exception will be thrown.

Parameters:
minCapacity The minimum number of array slots needed.
multiple The minimum capacity multiplier.

template<class T>
bool BasicArray< T >::isEmpty  )  const [inline]
 

Returns:
true if size is zero, false otherwise.

template<class T>
T& BasicArray< T >::operator[] const unsigned int  i  )  const [inline]
 

Allows you to access a BasicArray like a normal array.

See get().

template<class T>
void BasicArray< T >::put const unsigned int  i,
const T *  x,
const int  count
[inline]
 

Add an array of elements to the array.

Elements from i to count - 1 will be overwritten. If i + count is greater than the current size the array will automatically be increased.

Parameters:
i The starting index.
x A pointer to the elements to be added.
count The number of elements to copy into the array.

template<class T>
unsigned int BasicArray< T >::put const T *  x,
const int  count
[inline]
 

Add an array of elements to the end of the array.

Parameters:
x A pointer to the elements to be added.
count The number of elements to be added.
Returns:
The starting position of the added elements.

template<class T>
void BasicArray< T >::put const unsigned int  i,
const T &  x
[inline]
 

Add an array element.

If there is all ready an element at this index it will be overwritten. If the index is beyond the current size of the array the array size will be automatically increased.

Parameters:
i The index of the array element.
x The new array element.

template<class T>
unsigned int BasicArray< T >::put const T &  x  )  [inline]
 

Add the array element to the end of the array.

The size of the array will be increased by one. See the notes on the increase() function.

Parameters:
x A reference to the new array element
Returns:
The index of the new array element.

template<class T>
void BasicArray< T >::reset unsigned int  initialCapacity = 0  )  [inline]
 

Set size to zero and deallocate memory.

Parameters:
initialCapacity New capacity.

template<class T>
void BasicArray< T >::setSize const unsigned int  size  )  [inline]
 

setSize() will increase the array capacity if the new size is larger than the current capacity.

See also:
increase. If size is less than the current any array elements beyond the new size will no longer be accessable. setSize() does not deallocated any memory.
Parameters:
size The new array size.

template<class T>
void BasicArray< T >::shrink  )  [inline]
 

Calling this function assures that the array capacity is equal to its size by releasing any extra allocated memory.

shrink() should normally only be used after the last put() call and before a call to adopt(). However, when the difference between capacity and size is small the recovered memory will often not be usable because of memory fragmentation. As a rule of thumb do not bother with shrink() when array sizes are small or when you have only a few array instances. It is generally more efficient to set the array capacity in the constructor.

See also:
increase.


Member Data Documentation

template<class T>
unsigned int BasicArray< T >::capacity [private]
 

template<class T>
T* BasicArray< T >::data [private]
 

template<class T>
unsigned int BasicArray< T >::size [private]
 


The documentation for this class was generated from the following file:
Generated on Thu Sep 16 16:17:22 2004 for nostdinc by doxygen 1.3.8