c_collection

Table Of Contents

Introduction, c_collection

c_collection is the base class for all the other collection objects in this library. It contains member functions that are shared by the all other collection objects. This allows you to write code to the base class [c_collection], and swap in whatever container object best suites your needs at runtime.

The c_collection class, and all the derived classes are all template based. This allows the programmer to use collection objects to store virutaly any type of object. The only caveats are that the objects used in the collections must support a few basic functions (assuming that T is the stored type):

  • T( const T& ) - this is a standard copy constructor.
  • const T& operator=( const T& ) - this is a standard assingment operator.
  • int operator==( const T& ) - this is a standard equality operator.

c_collection is an abstract base class, so you cannot instantiate one, but it does provide a useable interface.

API Refrence
  • c_collection( void )

    This is the default constructor. It does nothing.

  • c_collection( const c_collection& that )

    This is a copy constructor, it only invokes operator=() (hopefuly) on the derived collection class.

  • virtual ~c_collection( void )

    This is the default destructor. It does nothing.

  • virtual int get_count( void ) const

    This is a pure virtual function, so it must be implemented by the derived collection class, and is meant to return a count of the elements in the collection.

  • virtual int add( const T& elm )

    This is a generic function used for adding elements to the collection. It is pure virtual in c_collection.

  • virtual int remove_all( void )

    In the derived classes, this fucntion should remove all the elements from the collection, and free all associated memory.

  • virtual c_collection_iter* prepare_iter( const collection_sorting_order ord = raw_order ) const

    This is how you obtain an iterator pointer when you want to iterate (step) through all of the elements in a collection. This function is pure virtual in c_collection.

  • virtual int first( c_collection_iter*, T& ) const
    virtual int next( c_collection_iter*, T& ) const
    virtual int prev( c_collection_iter*, T& ) const
    virtual int last( c_collection_iter*, T& ) const

    These functions are used to iterate through a collection. The only thing you have to watch out for during an iteration is that elements are not removed from the collection you are iterating through, or the iterator pointer can be come invalid. If you are aware that this condion has occured, you can deallocate the iterator without fear of derefrencing a bad pointer, otherwise it's behavior is undefined. To obtain the first element in the collection, use first(), and use last() to obtain the last element in the collection. Please note that weather or not the iteration follows any kind of logical order is dependant on the dervied collection object. next() returns the next element in the iteration, it is equivalent to first() if first has not yet been called, while prev() returns the previous element in the collection.

  • virtual int complete_iter( c_collection_iter* ) const

    This function needs to be called once for each invocation of prepare_iter(). prepare_iter() allocates memory, and complete_iter() must be called to clean it up.

Example Code for adding elemetns to a collection:
// 
// example code for adding entries to a collection
// 
void add_elements( c_collection<c_string>& stuff )
{
    stuff.add(c_string("string1"));
    stuff.add(c_string("string2"));
    stuff.add(c_string("string3"));
}
Example Code for iterating through a collection:
//
// iterate through a collection class using the 
//   base class functions:
//
void iterate( c_collection<c_string>& stuff )
{
    c_collection_iter<c_string> *iter = stuff.prepare_iter();
    c_string tmp;
    while( stuff.next( iter, tmp ) ) {
      cout << "The next element is:  " << tmp << endl;
    }
    return ;
}

Up