ELIST2 Class Reference

#include <elst2.h>

List of all members.

Detailed Description

Doubly linked lists with embedded links; generic list class.

Note:
dump() and de_dump() are not required as calls to dump/de_dump a list class should be handled by a class derived from this. make_serialise is not required for a similar reason.

Definition at line 91 of file elst2.h.

Public Member Functions

Private Member Functions

Private Attributes

Friends

Constructor & Destructor Documentation

ELIST2::ELIST2 (  )  [inline]

Definition at line 102 of file elst2.h.

References last(), and NULL.

00102              {  //constructor
00103       last = NULL;
00104     }

Member Function Documentation

void ELIST2::assign_to_sublist ( ELIST2_ITERATOR *  start_it,
ELIST2_ITERATOR *  end_it 
)

The list is set to a sublist of another list, which must be empty before this function is invoked.

The two iterators passed must refer to the same list, different from "this" one. The sublist removed is the inclusive list from start_it's current position to end_it's current position. If this range passes over the end of the source list then the source list has its end set to the previous element of start_it. The extracted sublist is unaffected by the end point of the source list, its end point is always the end_it position.

Definition at line 106 of file elst2.cpp.

References ABORT, empty(), ERRCODE::error(), ELIST2_ITERATOR::extract_sublist(), last, and NULL.

00108                                                         {  //from list end
00109   const ERRCODE LIST_NOT_EMPTY =
00110     "Destination list must be empty before extracting a sublist";
00111 
00112   #ifdef _DEBUG
00113   if (!this)
00114     NULL_OBJECT.error ("ELIST2::assign_to_sublist", ABORT, NULL);
00115   #endif
00116 
00117   if (!empty ())
00118     LIST_NOT_EMPTY.error ("ELIST2.assign_to_sublist", ABORT, NULL);
00119 
00120   last = start_it->extract_sublist (end_it);
00121 }

BOOL8 ELIST2::empty (  )  [inline]

Definition at line 110 of file elst2.h.

References last().

Referenced by ELIST2_ITERATOR::add_after_stay_put(), ELIST2_ITERATOR::add_after_then_move(), ELIST2_ITERATOR::add_before_stay_put(), ELIST2_ITERATOR::add_before_then_move(), ELIST2_ITERATOR::add_list_after(), ELIST2_ITERATOR::add_list_before(), assign_to_sublist(), ELIST2_ITERATOR::at_first(), ELIST2_ITERATOR::at_last(), ELIST2_ITERATOR::backward(), ELIST2_ITERATOR::cycled_list(), ELIST2_ITERATOR::data_relative(), ELIST2_ITERATOR::exchange(), ELIST2_ITERATOR::extract_sublist(), ELIST2_ITERATOR::forward(), internal_clear(), internal_dump(), and prep_serialise().

00110                   {  //is list empty?
00111       return !last;
00112     }

ELIST2_LINK* ELIST2::First (  )  [inline, private]

Definition at line 97 of file elst2.h.

References last(), list_rec::next, and NULL.

Referenced by ELIST2_ITERATOR::add_list_after(), ELIST2_ITERATOR::add_list_before(), ELIST2_ITERATOR::at_first(), ELIST2_ITERATOR::move_to_first(), and ELIST2_ITERATOR::set_to_list().

00097                        {  // return first
00098     return last ? last->next : NULL;
00099   }

void ELIST2::internal_clear ( void(*)(ELIST2_LINK *)  zapper  ) 

Destroy all links.

Used by the destructor and the "clear" member function of derived list classes to destroy all the elements on the list.

The calling function passes a "zapper" function which can be called to delete each element of the list, regardless of its derived type. This technique permits a generic clear function to destroy elements of different derived types correctly, without requiring virtual functions and the consequential memory overhead.

Definition at line 43 of file elst2.cpp.

References ABORT, empty(), last, ELIST2_LINK::next, and NULL.

00044                                 {
00045                                  //ptr to zapper functn
00046   ELIST2_LINK *ptr;
00047   ELIST2_LINK *next;
00048 
00049   #ifdef _DEBUG
00050   if (!this)
00051     NULL_OBJECT.error ("ELIST2::internal_clear", ABORT, NULL);
00052   #endif
00053 
00054   if (!empty ()) {
00055     ptr = last->next;            //set to first
00056     last->next = NULL;           //break circle
00057     last = NULL;                 //set list empty
00058     while (ptr) {
00059       next = ptr->next;
00060       zapper(ptr);
00061       ptr = next;
00062     }
00063   }
00064 }

void ELIST2::internal_de_dump ( FILE *  f,
ELIST2_LINK *  element_de_serialiser(FILE *) 
)

Cause each element on the list to be de_serialised.

Done by extracting the count of elements on the list, (held in the last member of the dumped version of the list object), and then de-serialising that number of list elements, adding each to the end of the reconstructed list.

Definition at line 245 of file elst2.cpp.

References ABORT, ELIST2_ITERATOR::add_to_end(), count(), last, ELIST2_LINK::next, NULL, ELIST2_LINK::prev, and ELIST2_ITERATOR::set_to_list().

00246                                               {
00247   INT32 count = (ptrdiff_t) last;
00248   ELIST2_ITERATOR this_it;
00249   ELIST2_LINK *de_serialised_element;
00250 
00251   #ifdef _DEBUG
00252   if (!this)
00253     NULL_OBJECT.error ("ELIST2::internal_de_dump", ABORT, NULL);
00254   #endif
00255 
00256   last = NULL;
00257   this_it.set_to_list (this);
00258   for (; count > 0; count--) {
00259     de_serialised_element = element_de_serialiser (f);
00260                                  //ignore old ptr
00261     de_serialised_element->next = NULL;
00262                                  //ignore old ptr
00263     de_serialised_element->prev = NULL;
00264     this_it.add_to_end (de_serialised_element);
00265   }
00266 }

void ELIST2::internal_deep_copy ( ELIST2_LINK *(*)(ELIST2_LINK *)  copier,
const ELIST2 *  list 
)

Used during explict deep copy of a list.

The "copier" function passed allows each element to be correctly deep copied (assuming that each class in the inheritance hierarchy does properly deep copies its members). The function passing technique is as for "internal_clear".

Definition at line 75 of file elst2.cpp.

References ABORT, ELIST2_ITERATOR::add_after_then_move(), ELIST2_ITERATOR::cycled_list(), ELIST2_ITERATOR::data(), ELIST2_ITERATOR::forward(), ELIST2_ITERATOR::mark_cycle_pt(), and NULL.

00077                         {           //list being copied
00078   ELIST2_ITERATOR from_it ((ELIST2 *) list);
00079   ELIST2_ITERATOR to_it(this);
00080 
00081   #ifdef _DEBUG
00082   if (!this)
00083     NULL_OBJECT.error ("ELIST2::internal_deep_copy", ABORT, NULL);
00084   if (!list)
00085     BAD_PARAMETER.error ("ELIST2::internal_deep_copy", ABORT,
00086       "source list is NULL");
00087   #endif
00088 
00089   for (from_it.mark_cycle_pt (); !from_it.cycled_list (); from_it.forward ())
00090     to_it.add_after_then_move (copier (from_it.data ()));
00091 }

void ELIST2::internal_dump ( FILE *  f,
void   element_serialiser(FILE *, ELIST2_LINK *) 
)

Cause each element on the list to be serialised by walking the list and calling the element_serialiser function for each element.

The element_serialiser simply does the appropriate coercion of the element to its real type and then invokes the elements serialise function

Definition at line 221 of file elst2.cpp.

References ABORT, ELIST2_ITERATOR::cycled_list(), ELIST2_ITERATOR::data(), empty(), ELIST2_ITERATOR::forward(), ELIST2_ITERATOR::mark_cycle_pt(), and NULL.

00222                                                  {
00223   ELIST2_ITERATOR this_it(this);
00224 
00225   #ifdef _DEBUG
00226   if (!this)
00227     NULL_OBJECT.error ("ELIST2::internal_dump", ABORT, NULL);
00228   #endif
00229 
00230   if (!empty ())
00231     for (this_it.mark_cycle_pt ();
00232     !this_it.cycled_list (); this_it.forward ())
00233   element_serialiser (f, this_it.data ());
00234 }

INT32 ELIST2::length (  ) 

Return count of elements on list.

Definition at line 127 of file elst2.cpp.

References ABORT, count(), ELIST2_ITERATOR::cycled_list(), ELIST2_ITERATOR::forward(), ELIST2_ITERATOR::mark_cycle_pt(), and NULL.

Referenced by ELIST2_ITERATOR::length(), and sort().

00127                      {  //count elements
00128   ELIST2_ITERATOR it(this);
00129   INT32 count = 0;
00130 
00131   #ifdef _DEBUG
00132   if (!this)
00133     NULL_OBJECT.error ("ELIST2::length", ABORT, NULL);
00134   #endif
00135 
00136   for (it.mark_cycle_pt (); !it.cycled_list (); it.forward ())
00137     count++;
00138   return count;
00139 }

void ELIST2::prep_serialise (  ) 

Replace the last member with a count of elements for serialisation.

This is used on list objects which are members of objects being serialised. The containing object has been shallow copied and this member function is invoked on the COPY.

Definition at line 194 of file elst2.cpp.

References ABORT, count(), ELIST2_ITERATOR::cycled_list(), empty(), ELIST2_ITERATOR::forward(), last, ELIST2_ITERATOR::mark_cycle_pt(), and NULL.

00194                             {
00195   ELIST2_ITERATOR this_it(this);
00196   INT32 count = 0;
00197 
00198   #ifdef _DEBUG
00199   if (!this)
00200     NULL_OBJECT.error ("ELIST2::prep_serialise", ABORT, NULL);
00201   #endif
00202 
00203   count = 0;
00204   if (!empty ())
00205     for (this_it.mark_cycle_pt ();
00206     !this_it.cycled_list (); this_it.forward ())
00207   count++;
00208   last = (ELIST2_LINK *) count;
00209 }

void ELIST2::shallow_copy ( ELIST2 *  from_list  )  [inline]

Definition at line 118 of file elst2.h.

References last, and last().

00119                                          {  //beware destructors!!
00120       last = from_list->last;
00121     }

BOOL8 ELIST2::singleton (  )  [inline]

Definition at line 114 of file elst2.h.

References FALSE, last(), and list_rec::next.

Referenced by ELIST2_ITERATOR::extract().

00114                       {
00115       return last ? (last == last->next) : FALSE;
00116     }

void ELIST2::sort ( int   comparator(const void *, const void *)  ) 

Sort elements on list.

NB If you dont like the const declarations in the comparator, coerce yours: ( int (*)(const void *, const void *)

Definition at line 149 of file elst2.cpp.

References ABORT, ELIST2_ITERATOR::add_to_end(), count(), ELIST2_ITERATOR::cycled_list(), ELIST2_ITERATOR::extract(), ELIST2_ITERATOR::forward(), length(), ELIST2_ITERATOR::mark_cycle_pt(), and NULL.

Referenced by ELIST2_ITERATOR::sort().

00151                              {
00152   ELIST2_ITERATOR it(this);
00153   INT32 count;
00154   ELIST2_LINK **base;            //ptr array to sort
00155   ELIST2_LINK **current;
00156   INT32 i;
00157 
00158   #ifdef _DEBUG
00159   if (!this)
00160     NULL_OBJECT.error ("ELIST2::sort", ABORT, NULL);
00161   #endif
00162 
00163   /* Allocate an array of pointers, one per list element */
00164   count = length ();
00165   base = (ELIST2_LINK **) malloc (count * sizeof (ELIST2_LINK *));
00166 
00167   /* Extract all elements, putting the pointers in the array */
00168   current = base;
00169   for (it.mark_cycle_pt (); !it.cycled_list (); it.forward ()) {
00170     *current = it.extract ();
00171     current++;
00172   }
00173 
00174   /* Sort the pointer array */
00175   qsort ((char *) base, count, sizeof (*base), comparator);
00176 
00177   /* Rebuild the list from the sorted pointers */
00178   current = base;
00179   for (i = 0; i < count; i++) {
00180     it.add_to_end (*current);
00181     current++;
00182   }
00183   free(base);
00184 }

Friends And Related Function Documentation

friend class ELIST2_ITERATOR [friend]

Definition at line 93 of file elst2.h.

Member Data Documentation

ELIST2_LINK* ELIST2::last [private]

Definition at line 95 of file elst2.h.

Referenced by ELIST2_ITERATOR::add_after_stay_put(), ELIST2_ITERATOR::add_after_then_move(), ELIST2_ITERATOR::add_before_stay_put(), ELIST2_ITERATOR::add_before_then_move(), ELIST2_ITERATOR::add_list_after(), ELIST2_ITERATOR::add_list_before(), ELIST2_ITERATOR::add_to_end(), assign_to_sublist(), ELIST2_ITERATOR::at_first(), ELIST2_ITERATOR::at_last(), ELIST2_ITERATOR::exchange(), ELIST2_ITERATOR::extract(), ELIST2_ITERATOR::extract_sublist(), internal_clear(), internal_de_dump(), ELIST2_ITERATOR::move_to_first(), ELIST2_ITERATOR::move_to_last(), prep_serialise(), ELIST2_ITERATOR::set_to_list(), and shallow_copy().

The documentation for this class was generated from the following files:
Generated on Wed Feb 28 19:49:31 2007 for Tesseract by  doxygen 1.5.1