RCArray< T > Class Template Reference

A reference counted, growable array template. More...

#include <RCArray.h>

Inheritance diagram for RCArray< T >:

[legend]Collaboration diagram for RCArray< T >:

[legend]List of all members.

Public Member Functions
	RCArray ()
	Argumentless constructor: the RCArray will contain no data elements.
ValRef	operator[] (const int ix) throw (std::out_of_range)
T	operator[] (const int ix) const
ValRef	operator[] (const size_t ix) throw (std::out_of_range)
T	operator[] (const size_t ix) const
void	append (T val)
	Add a new element to the end of the RCArray, resulting in length() + 1 data elements.
Protected Member Functions
void	init (T intialVal)
	Initialize the array with a value of type T.
	RCArray (size_t initialSize)
	Create an RCArray with length() == initialSize.
	RCArray (size_t initialSize, T initVal)
	Create an RCArray with length() == initialSize, where length() data elements are initialized to initialValue.
T	read (const int i) const
	Return the element at index i.
void	write (const int i, const T v)
	Write value v at index i.
size_t	length () const
	Return the number of data elements in the RCArray.
size_t	getRefCnt ()
	Return the reference count.
Protected Attributes
RCPtr< SharedData >	value

---

Detailed Description

template<class T>
class RCArray< T >

A reference counted, growable array template.

Objects that are instantiated with this template have three characteristics:

1. An assignment of the object increments the reference count rather than copying memory. For example, in the code below myObj1 is initialized and then assigned to myObj2. myObj1 and myObj2 now share the same memory (there was no copy) and the reference count will be 2.

   
       #include <iostream>
       #include "RCArray.h"

       typedef RCArray<int> IntVec;

       main()
       {
         IntVec myObj1, myObj2;

         for (int i = 1; i <= 10; i++) {
           myObj1.append( i );
         }
         myObj2 = myObj1;
         for (i = 0; i < 10; i++) {
           std::cout << myObj2[i] << " ";
         }
         std::cout << std::endl;
       }
      

   If this code is complex and executed it will print:

   
      1 2 3 4 5 6 7 8 9 10
      

2. A change to an object with multiple references results in a copy-on-write. That instance of the object will be changed while the others remain unchanged. Since a unique copy has been made, the reference count will be reduced by one. For example, the assignment

   
            myObj1[4] = 42;
      

   will only change myObj1. The contents of myObj2 remain {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}.

3. When the reference count reaches zero, the memory for the object will be automatically deallocated. This allows reference counted array used as if they were elemental values, without worrying about memory allocation and deallocation.

Only the argumentless constructor of RCArray is made public. Classes can expose the other constructors and protected functions like length() and getRefCnt() (which is useful in testing and verification) by deriving a class from an instance of this template. For example:

    #include "RCArray.h"

    typedef RCArray<double> DoubleArray;

    class DoubleVec : public DoubleArray
    {
    private:
      void init(double intialVal );
    public:
      DoubleVec() : DoubleArray() {}
      DoubleVec(size_t initialSize) : DoubleArray( initialSize ) {}
      DoubleVec(size_t initialSize, double initVal ) : 
        DoubleArray(initialSize, initVal) {}

      size_t length() { return DoubleArray::length(); }
      size_t getRefCnt() { return DoubleArray::getRefCnt(); }
    };
   

The RCArray template has a single data element, value, which is a "smart" pointer. Note that there is no overloaded assignment operator. The default RCArray assignment copies the value element. This in turn results in a copy of the RCPtr instantiated template object (the smart pointer).

The RCArray template uses the default destructor (oh, the horror!) The default destructor will call the destructor on value which will, in turn invoke the removeReference() function in RCObject. This will decrement the reference count. When the reference count reaches zero, the shared data will be deleted.

Compiling the code

The GrowableArray template will throw a runtime exception if the array is indexed beyond the bounds of the data. At least in the case of the Microsoft compilers, this requires that you include the -GX flag. For example:

      cl -TP -GX -Zi test.C -o test

(the -Zi flag compiles for debug).

Definition at line 156 of file RCArray.h.

---

Constructor & Destructor Documentation

template<class T> RCArray< T >::RCArray (  size_t  initialSize  )  [inline, protected]

Create an RCArray with length() == initialSize. The length() data elements are uninitialized and their value is undefined. Definition at line 235 of file RCArray.h. : value( new SharedData(initialSize) ) {}

template<class T> RCArray< T >::RCArray (  size_t  initialSize, T  initialVal )  [inline, protected]

Create an RCArray with length() == initialSize, where length() data elements are initialized to initialValue. Definition at line 245 of file RCArray.h. References RCArray< T >::init(). : value( new SharedData(initialSize) ) { init( initialVal ); }

template<class T> RCArray< T >::RCArray (   )  [inline]

Argumentless constructor: the RCArray will contain no data elements. Definition at line 226 of file RCArray.h. : value( new SharedData() ) {}

---

Member Function Documentation

template<class T> void RCArray< T >::append (  T  val  )  [inline]

Add a new element to the end of the RCArray, resulting in length() + 1 data elements. Definition at line 258 of file RCArray.h. References RCArray< T >::value. { value->data.append( val ); }

template<class T> size_t RCArray< T >::getRefCnt (   )  [inline, protected]

Return the reference count. Reimplemented in DoubleVec, and String. Definition at line 279 of file RCArray.h. References RCArray< T >::value. { return value->getRefCnt(); }

template<class T> void RCArray< T >::init (  T  initialVal  )  [inline, protected]

Initialize the array with a value of type T. Reimplemented in DoubleVec. Definition at line 213 of file RCArray.h. References RCArray< T >::value. Referenced by RCArray< T >::RCArray(). { size_t len = value->data.length(); for (size_t i = 0; i < len; i++) { value->data[i] = initialVal; } }

template<class T> size_t RCArray< T >::length (  void   )  const [inline, protected]

Return the number of data elements in the RCArray. Definition at line 268 of file RCArray.h. References RCArray< T >::value. { return value->data.length(); }

template<class T> T RCArray< T >::operator[] (  const size_t  ix  )  const [inline]

Definition at line 310 of file RCArray.h. References RCArray< T >::value. { return value->data[ix]; }

template<class T> RCArray< T >::ValRef RCArray< T >::operator[] (  const size_t  ix  )  throw (std::out_of_range) [inline]

Definition at line 317 of file RCArray.h. { if (ix >= value->data.length()) { const char *errMsg = "operator[] - index out of bounds"; throw std::out_of_range( errMsg ); } return ValRef( *this, ix ); }

template<class T> T RCArray< T >::operator[] (  const int  ix  )  const [inline]

Definition at line 288 of file RCArray.h. References RCArray< T >::value. { return value->data[ix]; }

template<class T> RCArray< T >::ValRef RCArray< T >::operator[] (  const int  ix  )  throw (std::out_of_range) [inline]

Definition at line 297 of file RCArray.h. { if (ix < 0 || ix >= value->data.length()) { const char *errMsg = "operator[] - index out of bounds"; throw std::out_of_range( errMsg ); } return ValRef( *this, ix ); }

template<class T> T RCArray< T >::read (  const int  i  )  const [inline, protected, virtual]

Return the element at index i. Implements RCBase< T >. Definition at line 333 of file RCArray.h. References RCArray< T >::value. { return value->data[i]; }

template<class T> void RCArray< T >::write (  const int  i, const T  v )  [inline, protected, virtual]

Write value v at index i. Implements RCBase< T >. Definition at line 344 of file RCArray.h. References RCArray< T >::value. { if (value->isShared()) { value = new SharedData( value->data ); } value->data[i] = v; }

---

Member Data Documentation

template<class T> RCPtr<SharedData> RCArray< T >::value [protected]

Definition at line 182 of file RCArray.h. Referenced by RCArray< T >::append(), RCArray< T >::getRefCnt(), RCArray< T >::init(), RCArray< T >::length(), RCArray< T >::operator[](), RCArray< T >::read(), and RCArray< T >::write().

---

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

• RCArray.h

---