# BasicArray< T > Class Template Reference

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

`#include <BasicArray.h>`

Collaboration diagram for BasicArray< T >:

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

- BasicArray.h