BasicArray Class Template Reference

A array data type that manages the allocation and deallocation of memory. More...

#include <BasicArray.h>

Inheritance diagram for BasicArray::

SimpleArray NumArray List of all members.

Public Methods

 BasicArray ()
 Empty constructor.

 BasicArray (const size_type mylen, T *d=((T *) 0), const EnumDataOwned o=DataNotOwned)
 Constructor that initializes the length and possibly data. More...

 BasicArray (const BasicArray< T > &array)
 Copy constructor.

virtual ~BasicArray ()
 Destructor.

int shared_mem () const
 Returns TRUE if this array shares data with another array.

virtual int resize (const size_type newl)
 Resizes the array to the given, nonnegative, value.

size_type size () const
 Returns the length of the array.

int len () const
 Returns the length of the array. This method is deprecated.

T * data () const
 Returns the internal pointer to the array.

 operator T * () const
 A coercion operator, which returns a pointer to the internal array.

int nrefs () const
 Returns the number of references to the internal array.

T & operator[] (const int i)
 Accesses the i-th element of the array. More...

const T & operator[] (const int i) const
 Accesss the i-th element of the array and returns a const.

T & operator[] (const size_type i)
 Accesses the i-th element of the array. More...

const T & operator[] (const size_type i) const
 Accesss the i-th element of the array and returns a const.

BasicArray< T > & operator= (const BasicArray< T > &array)
 Copies the array object by constructing a new BasicArray.

BasicArray< T > & operator &= (const BasicArray< T > &array)
 Copies the pointer from the array object and increments the data's reference counter.

BasicArray< T > & operator &= (BasicArray< T > &array)
 Copies the pointer from the array object and increments the data's reference counter, updating array if it is not shared.

BasicArray< T > & operator= (const T &val)
 Set all elements of the array to val.

BasicArray< T > & set_data (const size_type len, T *data, const EnumDataOwned o=DataNotOwned)
 Method to explicitly set the internal data array to a pointer array.

BasicArray< T > & set_data (const BasicArray< T > &vec, const size_type start, const size_type newlen)
 Method to explicitly set the internal data array to share the data in a BasicArray. More...

BasicArray< T > & set_data (const BasicArray< T > &vec, const size_type start=0)
 Calls set_data with a default value for newlen.

BasicArray< T > & set_subvec (const size_type start, const size_type len, const BasicArray< T > &datavec, const size_type offset=0)
 Copy a subvector of a BasicArray into the current array.

BasicArray< T > & at (const size_type start, const size_type newlen, BasicArray< T > *array=(BasicArray< T > *) 0) const
 This works like the set_data method.

BasicArray< T > & at (const size_type start=0) const
 This works like the set_data method.

void append (T &element)
 Resize and append an element onto the array.

void append (BasicArray< T > &vec)
 Resize and append an array onto the array.

void freeze_memory ()
 Freeze the array allocation, to facilitate array sharing.


Static Public Methods

void set_ref_limit (const int num)
 Set reference counter limit.


Protected Methods

virtual void construct (const size_type mylen, T *d, const EnumDataOwned o=DataNotOwned)
 Method used by constructors to setup the BasicArray class.

virtual void initialize (T *, const size_type, const size_type)
 Virtual method that is used by numeric arrays to initalize the array.

void free ()
 Method used to delete the internal array class.

void set_shared_data (T *data, const size_type len_, const EnumDataOwned o=DataNotOwned)
 Method to explicitly set the shared data array to a pointer array.


Protected Attributes

T * Data
 The pointer to this array's data.

size_type Len
 The length of the array in Data.

ArrayRef< T, BasicArray< T > > * shared
 Pointer to the structure that maintains the shared pointer.


Friends

class ArrayRef< T, BasicArray< T > >

Detailed Description

template<class T>
class BasicArray< T >

A array data type that manages the allocation and deallocation of memory.

This code is strongly influenced on the discussion of reference counting in C. S. Horstmann, "Mastering C++ - An introduction to C++ and object-oriented programming for C and Pascal programmers." This code represents an extension of the vector class developed by Brian Bartell, UC San Diego.

To minimize the memory impact of these arrays, the reference count is only used when needed. Specifically, the ArrayRef class is used (1) when a constructor passes data that is not owned by the array or (2) after methods like operator &= and set_data are called, which initiate the use of reference counting. Thus by default the memory usage of a BasicArray is a pointer, an integer counter and the memory in the array.

Note that this memory optimization requires that the class ArrayRef know about all of the classes that have pointers to its data. This is somewhat dangerous, since you can run into cases where the many arrays are shared, at which point the sharing mechanism becomes quite cumbersome. However, these cases appear to be rare, and this code reflects the common usage of this class. The set_ref_limit() method can be used to set the maximum number of references allowed in a code. When this is exceeded, this code aborts.

This method for reference counting incurs some overhead, especially when arrays are added or deleted, and when arrays are resized. When arrays are fixed but widely shared, the freeze_memory() method can be called. This sets up the ArrayRef object such that the array it manages cannot be modified (e.g. with the set_data() or resize() methods). Presently, there is no mechanism to 'unfreeze' and array, since frozen arrays are optimized, in part, by eliminating some bookkeeping arrays in the ArrayRef object.

Constructor & Destructor Documentation

template<class T>
BasicArray< T >::BasicArray (  const size_type    mylen,
T *    d = ((T*)0),
const EnumDataOwned    o = DataNotOwned
)  [inline, explicit]
 

Constructor that initializes the length and possibly data.

The len parameter specifies the length of the array. If the d parameter is not null, then this array is assumed to have length len. The initialization of the array then depends upon the value of the o parameter. If o is DataNotOwned (the default), then the data is copied from d. Otherwise, the internal point is set to d and the internal ownership flag is set to o.

Member Function Documentation

template<class T>
T & BasicArray< T >::operator[] (  const size_type    idx )  [inline]
 

Accesses the i-th element of the array.

This method gives BasicArray's the same look-and-feel as C arrays. Note that the index for these arrays begins at zero. This method returns a modifiable data element.

template<class T>
T & BasicArray< T >::operator[] (  const int    idx )  [inline]
 

Accesses the i-th element of the array.

This method gives BasicArray's the same look-and-feel as C arrays. Note that the index for these arrays begins at zero. This method returns a modifiable data element.

template<class T>
BasicArray< T > & BasicArray< T >::set_data (  const BasicArray< T > &    array,
const size_type    start,
const size_type    newlen
) 
 

Method to explicitly set the internal data array to share the data in a BasicArray.

The start parameter specifies the initial point in the BasicArray, and newlen specifies the length of the subvector that the current array object sees.

The documentation for this class was generated from the following file: