CLIST Class Reference

#include <clst.h>

List of all members.

---

Detailed Description

Generic list class for singly linked CONS cell lists.

Definition at line 104 of file clst.h.

Public Member Functions

• void assign_to_sublist (CLIST_ITERATOR *start_it, CLIST_ITERATOR *end_it)

  The list is set to a sublist of another list.
  

• CLIST ()
• BOOL8 empty ()
• void internal_de_dump (FILE *f, void *element_de_serialiser(FILE *))

  Cause each element on the list to be de_serialised 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.
  

• void internal_deep_clear (void(*zapper)(void *))

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

• void internal_deep_copy (void *(*copier)(void *), const CLIST *list)

  Used during explict deep copy of a list.
  

• void internal_dump (FILE *f, void element_serialiser(FILE *, void *))

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

• INT32 length ()

  Return count of elements on list.
  

• void prep_serialise ()

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

• void shallow_clear ()

  Destroy all links.
  

• void shallow_copy (CLIST *from_list)
• BOOL8 singleton ()
• void sort (int comparator(const void *, const void *))

  Sort elements on list.
  

• ~CLIST ()

Private Member Functions

• CLIST_LINK * First ()

Private Attributes

• CLIST_LINK * last

Friends

• class CLIST_ITERATOR

---

Constructor & Destructor Documentation

CLIST::CLIST

(

)

[inline]

Definition at line 115 of file clst.h.

References last(), and NULL.

            {  //constructor
      last = NULL;
    }

CLIST::~CLIST

(

)

[inline]

Definition at line 119 of file clst.h.

              {                  //destructor
      shallow_clear();
    }

---

Member Function Documentation

void CLIST::assign_to_sublist	(	CLIST_ITERATOR *	start_it,
		CLIST_ITERATOR *	end_it
	)

The list is set to a sublist of another list.

"This" list 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 136 of file clst.cpp.

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

                                                      {  //from list end
  const ERRCODE LIST_NOT_EMPTY =
    "Destination list must be empty before extracting a sublist";

  #ifdef _DEBUG
  if (!this)
    NULL_OBJECT.error ("CLIST::assign_to_sublist", ABORT, NULL);
  #endif

  if (!empty ())
    LIST_NOT_EMPTY.error ("CLIST.assign_to_sublist", ABORT, NULL);

  last = start_it->extract_sublist (end_it);
}

BOOL8 CLIST::empty

(

)

[inline]

Definition at line 129 of file clst.h.

References last().

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

                  {  //is list empty?
      return !last;
    }

CLIST_LINK* CLIST::First

(

)

[inline, private]

Definition at line 110 of file clst.h.

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

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

                      {  // return first
    return last != NULL ? last->next : NULL;
  }

void CLIST::internal_de_dump	(	FILE *	f,
		void *	element_de_serialiser(FILE *)
	)

Cause each element on the list to be de_serialised 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 271 of file clst.cpp.

References ABORT, CLIST_ITERATOR::add_to_end(), count(), last, NULL, and CLIST_ITERATOR::set_to_list().

                                                                       {
  INT32 count = (ptrdiff_t) last;
  CLIST_ITERATOR this_it;

  #ifdef _DEBUG
  if (!this)
    NULL_OBJECT.error ("CLIST::internal_de_dump", ABORT, NULL);
  #endif

  last = NULL;
  this_it.set_to_list (this);
  for (; count > 0; count--)
    this_it.add_to_end (element_de_serialiser (f));
}

void CLIST::internal_deep_clear

(

void(*)(void *)

zapper

)

Used by the "deep_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 data element of the list, regardless of its class. 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 40 of file clst.cpp.

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

                         {       //ptr to zapper functn
  CLIST_LINK *ptr;
  CLIST_LINK *next;

  #ifdef _DEBUG
  if (!this)
    NULL_OBJECT.error ("CLIST::internal_deep_clear", ABORT, NULL);
  #endif

  if (!empty ()) {
    ptr = last->next;            //set to first
    last->next = NULL;           //break circle
    last = NULL;                 //set list empty
    while (ptr) {
      next = ptr->next;
      zapper (ptr->data);
      delete(ptr);
      ptr = next;
    }
  }
}

void CLIST::internal_deep_copy	(	void *(*)(void *)	copier,
		const CLIST *	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 102 of file clst.cpp.

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

                       {            //list being copied
  CLIST_ITERATOR from_it ((CLIST *) list);
  CLIST_ITERATOR to_it(this);

  #ifdef _DEBUG
  if (!this)
    NULL_OBJECT.error ("CLIST::internal_deep_copy", ABORT, NULL);
  if (!list)
    BAD_PARAMETER.error ("CLIST::internal_deep_copy", ABORT,
      "source list is NULL");
  #endif

  for (from_it.mark_cycle_pt (); !from_it.cycled_list (); from_it.forward ())
    to_it.add_after_then_move (copier (from_it.data ()));
}

void CLIST::internal_dump	(	FILE *	f,
		void	element_serialiser(FILE *, void *)
	)

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 249 of file clst.cpp.

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

                                                                        {
  CLIST_ITERATOR this_it(this);

  #ifdef _DEBUG
  if (!this)
    NULL_OBJECT.error ("CLIST::internal_dump", ABORT, NULL);
  #endif

  if (!empty ())
    for (this_it.mark_cycle_pt ();
    !this_it.cycled_list (); this_it.forward ())
  element_serialiser (f, this_it.data ());
}

INT32 CLIST::length

(

)

Return count of elements on list.

Definition at line 157 of file clst.cpp.

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

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

                    {  //count elements
  CLIST_ITERATOR it(this);
  INT32 count = 0;

  #ifdef _DEBUG
  if (!this)
    NULL_OBJECT.error ("CLIST::length", ABORT, NULL);
  #endif

  for (it.mark_cycle_pt (); !it.cycled_list (); it.forward ())
    count++;
  return count;
}

void CLIST::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 221 of file clst.cpp.

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

                           {
  CLIST_ITERATOR this_it(this);
  INT32 count = 0;

  #ifdef _DEBUG
  if (!this)
    NULL_OBJECT.error ("CLIST::prep_serialise", ABORT, NULL);
  #endif

  count = 0;
  if (!empty ())
    for (this_it.mark_cycle_pt ();
    !this_it.cycled_list (); this_it.forward ())
  count++;
  last = (CLIST_LINK *) count;
}

void CLIST::shallow_clear

(

)

Destroy all links.

Used by the destructor and the "shallow_clear" member function of derived list classes to destroy the list.

The data elements are NOT destroyed.

Definition at line 72 of file clst.cpp.

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

                          {  //destroy all links
  CLIST_LINK *ptr;
  CLIST_LINK *next;

  #ifdef _DEBUG
  if (!this)
    NULL_OBJECT.error ("CLIST::shallow_clear", ABORT, NULL);
  #endif

  if (!empty ()) {
    ptr = last->next;            //set to first
    last->next = NULL;           //break circle
    last = NULL;                 //set list empty
    while (ptr) {
      next = ptr->next;
      delete(ptr);
      ptr = next;
    }
  }
}

void CLIST::shallow_copy

(

CLIST *

from_list

)

[inline]

Definition at line 137 of file clst.h.

References last, and last().

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

BOOL8 CLIST::singleton

(

)

[inline]

Definition at line 133 of file clst.h.

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

Referenced by CLIST_ITERATOR::extract().

                      {
      return last != NULL ? (last == last->next) : FALSE;
    }

void CLIST::sort

(

int

comparator(const void *, const void *)

)

Sort elements on list.

Definition at line 176 of file clst.cpp.

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

Referenced by CLIST_ITERATOR::sort().

                             {
  CLIST_ITERATOR it(this);
  INT32 count;
  void **base;                   //ptr array to sort
  void **current;
  INT32 i;

  #ifdef _DEBUG
  if (!this)
    NULL_OBJECT.error ("CLIST::sort", ABORT, NULL);
  #endif

  /* Allocate an array of pointers, one per list element */
  count = length ();
  base = (void **) malloc (count * sizeof (void *));

  /* Extract all elements, putting the pointers in the array */
  current = base;
  for (it.mark_cycle_pt (); !it.cycled_list (); it.forward ()) {
    *current = it.extract ();
    current++;
  }

  /* Sort the pointer array */
  qsort ((char *) base, count, sizeof (*base), comparator);

  /* Rebuild the list from the sorted pointers */
  current = base;
  for (i = 0; i < count; i++) {
    it.add_to_end (*current);
    current++;
  }
  free(base);
}

---

Friends And Related Function Documentation

friend class CLIST_ITERATOR [friend]

Definition at line 106 of file clst.h.

---

Member Data Documentation

CLIST_LINK* CLIST::last [private]

Definition at line 108 of file clst.h.

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

---

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

• ccutil/clst.h
• ccutil/clst.cpp

---