container::List Class Reference

Abstract base class for all list containers. More...

#include <list.h>

Inheritance diagram for container::List:

[legend]

Collaboration diagram for container::List:

[legend]

List of all members.

Public Member Functions
virtual	~List ()
bool	add (Entity *entity)
	Add an Entity to the list.
bool	deleteCurrent ()
	Remove the current Entity from the list and delete it from memory.
Entity *	extractCurrentEntity ()
	Remove the current Entity from the list and return a pointer to it.
virtual bool	isFirst () const =0
	Return true if the cursor is pointing to first real node, false otherwise.
virtual bool	isLast () const =0
	Determine whether the list cursor is pointing to the last Entity.
virtual bool	isTail () const =0
	Return true if the cursor is pointing to the list tail, false otherwise.
virtual bool	toFirst ()=0
	Point the cursor to the first Entity in the list.
virtual bool	toLast ()=0
	Point the cursor to the last Entity in the list.
virtual void	toTail ()=0
	Point the cursor to the tail of the list.
virtual bool	toNext ()=0
	Point the cursor to the next Entity in the list.
virtual bool	toPrev ()=0
	Point the cursor to the previous Entity in the list.
virtual Entity *	currentEntity ()=0
	Return a pointer to the current Entity.
virtual void	locateEntity (const Entity &key, int &index, Entity *&entity)=0
	Locate the first Entity that matches the specified key.
virtual Entity *	entityAt (int index)=0
	Return a pointer to the Entity found at the specified, zero-based index.
int	purgeContents ()
	Empty the contents of the container, deleting all Entities.
virtual ostream &	renderState (ostream &os) const
	Write the state of an Object for debugging and demonstration.
virtual const Info *	typeInfo () const
	Return the instance of Object::Info that describes the class of this object.
virtual Object *	clone (bool deepCopy=false) const =0
	A polymorphic copy constructor.
Static Public Attributes
static const Info *const	TYPE_INFO = Object::typeInfoFactory("List")
static const int	NO_MATCHING_ENTITY_INDEX_FLAG = -1
	Returned as an index value by method locateEntity() when a matching entity was not found in the list.
Protected Member Functions
	List ()
	List (const List &orig)
virtual bool	deleteCurrent_impl ()=0
	Called by a template method.
virtual Entity *	extractCurrentEntity_impl ()=0
	Called by a template method.
virtual bool	add_impl (Entity *entity)=0
	Called by a template method.

---

Detailed Description

Abstract base class for all list containers.

May allow duplicates. Derived classes may choose to disallow duplicates.

---

Constructor & Destructor Documentation

container::List::List

(

)

[protected]

{ }

container::List::List

(

const List &

orig

)

[protected]

{ }

container::List::~List

(

)

[virtual]

{ }

---

Member Function Documentation

bool container::List::add

(

Entity *

entity

)

Add an Entity to the list.

This is the default method for adding an Entity object to a List. Derived classes determine the exact behavior: where in the list it will be added, whether duplicates are allowed, etc. As with all methods that add items to a Container, no copy of the Entity is made. The Container takes responsibility to delete the Entity.

Returns:

true if the Entity was added; otherwise false

Postcondition:

If true is returned then the Entity is in the List and the Container's count is greater by one.

If false is returned then the List's state is unchanged

In either case (a return value of true or false) the list cursor will remain unchanged. It will not be pointing to the new Entity.

                             {
   int oldCount = getCount();
   if (add_impl(entity)) {
      if (oldCount == getCount()) {
         incCount();
      }
      return true;
   }

   return false;
}

Here is the call graph for this function:

Here is the caller graph for this function:

virtual bool container::List::add_impl

(

Entity *

entity

)

[protected, pure virtual]

Called by a template method.

See also:

Details documented in List::add

Implemented in container::OrderedArrayList, container::OrderedLinkedList, container::SortedArrayList, and container::SortedLinkedList.

Here is the caller graph for this function:

virtual Object* container::List::clone

(

bool

deepCopy = false

)

const [pure virtual]

A polymorphic copy constructor.

Implements container::Container.

Implemented in container::ArrayList, container::OrderedArrayList, container::OrderedLinkedList, container::OrderedList, container::SortedArrayList, container::SortedLinkedList, and container::SortedList.

virtual Entity* container::List::currentEntity

(

)

[pure virtual]

Return a pointer to the current Entity.

Returns:

A pointer to the current Entity object. Returns NULL if the list was empty or if the cursor was not pointing to an Entity.

Precondition:

The list cursor points to an Entity

Postcondition:

The current Entity remains in the list

The state of the List is unchanged

Implemented in container::ArrayList, and container::LinkedList.

Here is the caller graph for this function:

bool container::List::deleteCurrent

(

)

Remove the current Entity from the list and delete it from memory.

Returns:

true if an Entity was removed. false if the cursor was not pointing to an Entity.

Precondition:

The list is not empty

The list cursor points an Entity

Postcondition:

The Entity indicated by the cursor is no longer in the list

The Entity indicated by the cursor is deleted from memory

The cursor points to the next Entity in the list or to the tail of the list if the deleted Entity was last

                         {
   if (deleteCurrent_impl()) {
      decCount();
      return true;
   }

   return false;
}

Here is the call graph for this function:

Here is the caller graph for this function:

virtual bool container::List::deleteCurrent_impl

(

)

[protected, pure virtual]

Called by a template method.

See also:

Details documented in List::deleteCurrent

Implemented in container::ArrayList, and container::LinkedList.

Here is the caller graph for this function:

virtual Entity* container::List::entityAt

(

int

index

)

[pure virtual]

Return a pointer to the Entity found at the specified, zero-based index.

Returns:

A pointer to the Entity at the specified index

Precondition:

The List must contain at least one Entity object.

A valid index must be specified. For example, if count is 1 then the only valid index is 0.

Postcondition:

The state of the list is unchanged including the cursor position

Implemented in container::ArrayList, and container::LinkedList.

Here is the caller graph for this function:

Entity * container::List::extractCurrentEntity

(

)

Remove the current Entity from the list and return a pointer to it.

The caller becomes responsible for disposing of the Entity. If successful, the list cursor ends up pointing the next Entity in the list.

Returns:

A pointer to the extracted Entity. NULL if the list was empty or if the cursor was not pointing to an Entity.

Precondition:

The list cursor points to the Entity to be extracted

Postcondition:

The Entity (formerly the current Entity) is not in the list

The caller is responsible for deleting the extracted Entity

The list cursor points to the next Entity in the list or to the tail of the list if the extracted Entity was last

                                    {
   Entity * e = extractCurrentEntity_impl();
   decCount();
   return e;
}

Here is the call graph for this function:

Here is the caller graph for this function:

virtual Entity* container::List::extractCurrentEntity_impl

(

)

[protected, pure virtual]

Called by a template method.

See also:

Details documented in List::extractCurrentEntity

Implemented in container::ArrayList, and container::LinkedList.

Here is the caller graph for this function:

virtual bool container::List::isFirst

(

)

const [pure virtual]

Return true if the cursor is pointing to first real node, false otherwise.

TRUE is only possible if the list is not empty.

Implemented in container::ArrayList, and container::LinkedList.

Here is the caller graph for this function:

virtual bool container::List::isLast

(

)

const [pure virtual]

Determine whether the list cursor is pointing to the last Entity.

true is only possible if the list is not empty.

Returns:

true if the list cursor is pointing to the last Entity of the list, false otherwise

Implemented in container::ArrayList, and container::LinkedList.

Here is the caller graph for this function:

virtual bool container::List::isTail

(

)

const [pure virtual]

Return true if the cursor is pointing to the list tail, false otherwise.

false is only possible if the list is not empty.

Implemented in container::ArrayList, and container::LinkedList.

Here is the caller graph for this function:

virtual void container::List::locateEntity	(	const Entity &	key,
		int &	index,
		Entity *&	entity
	)			[pure virtual]

Locate the first Entity that matches the specified key.

The position is returned as a zero based index. The first Entity that matches is returned. No further checking of the list is performed.

Returns:

The zero based index of the matching Entity. If a matching Entity is not found List::NO_MATCHING_ENTITY_INDEX_FLAG is returned in index instead.

entity will point to the matching Entity. If a matching Entity is not found, NULL is returned in entity instead.

Precondition:

A matching Entity is in the list

Postcondition:

The state of the list is unchanged including the cursor position

Implemented in container::ArrayList, container::LinkedList, and container::SortedArrayList.

Here is the caller graph for this function:

int container::List::purgeContents

(

)

[virtual]

Empty the contents of the container, deleting all Entities.

This method is used by the destructor.

Returns:

The number of Entity objects deleted

Postcondition:

isEmpty() is true

The memory for all Entities is freed

Implements container::Container.

                        {
   if (!toFirst()) return 0;
   int i = 0;
   while (deleteCurrent()) {
      i++;
   }
   return i;
}

Here is the call graph for this function:

Here is the caller graph for this function:

ostream & container::List::renderState

(

ostream &

os

)

const [virtual]

Write the state of an Object for debugging and demonstration.

This method must not change the state of an Object; adding or removing debug statements should not change the behavior of a class. The implementation must be robust, e.g., NULL safe, etc. and work without an unrecoverable error for any state, excluding an Object's time of construction and destruction. It is not required for the implementation to be thread safe.

Precondition:

The Object has been fully constructed and is not in the process of destruction

Postcondition:

The state of the Object is unchanged

Reimplemented from container::Container.

Reimplemented in container::ArrayList, container::LinkedList, container::OrderedArrayList, container::OrderedLinkedList, container::OrderedList, container::SortedArrayList, container::SortedLinkedList, and container::SortedList.

                                             {
   return this->Container::renderState(os);
}

virtual bool container::List::toFirst

(

)

[pure virtual]

Point the cursor to the first Entity in the list.

Returns:

false if the list is empty; otherwise, true. A value of true doesn't imply that the cursor was moved, i.e., it may have already been pointing to the first Entity.

Precondition:

The list is not empty

Postcondition:

The list cursor points to the first Entity in the list

Implemented in container::ArrayList, and container::LinkedList.

Here is the caller graph for this function:

virtual bool container::List::toLast

(

)

[pure virtual]

Point the cursor to the last Entity in the list.

Returns:

false if the list is empty; otherwise, true. A value of true doesn't imply that the cursor was moved, i.e., it may have already been pointing to the last Entity.

Precondition:

The list is not empty

Postcondition:

The list cursor points to the last Entity in the list

Implemented in container::ArrayList, and container::LinkedList.

Here is the caller graph for this function:

virtual bool container::List::toNext

(

)

[pure virtual]

Point the cursor to the next Entity in the list.

Returns:

true if the list cursor was moved and points to an Entity

false if the cursor was moved to the tail of list

false if the cursor was already pointing to the tail

Precondition:

The List is not empty

The list cursor is not pointing to the tail

Postcondition:

The list cursor has moved to the next Entity or to the tail if it was pointing to the last Entity

Implemented in container::ArrayList, and container::LinkedList.

Here is the caller graph for this function:

virtual bool container::List::toPrev

(

)

[pure virtual]

Point the cursor to the previous Entity in the list.

Calling toPrev() never leaves the cursor pointing to the head of the list.

Returns:

true if the list cursor was moved

false if the cursor is already pointing the first Entity in the list

false if the list is empty

Precondition:

The list is not empty

The list cursor is not pointing to the first Entity in the list

Postcondition:

The list cursor has moved to the previous Entity

Implemented in container::ArrayList, and container::LinkedList.

Here is the caller graph for this function:

virtual void container::List::toTail

(

)

[pure virtual]

Point the cursor to the tail of the list.

This method should always succeed. A List should always have the concept a tail, i.e., the node or element just beyond the end of the list. No Entity is available at the tail cursor position.

Precondition:

A List has been constructed

Postcondition:

The list cursor points to the tail

Implemented in container::ArrayList, and container::LinkedList.

Here is the caller graph for this function:

const Object::Info * container::List::typeInfo

(

)

const [virtual]

Return the instance of Object::Info that describes the class of this object.

Instantiation of Object::Info is controlled by the protected method Object::typeInfoFactory(const string&). Each sub-class of Object should create one and only one instance of Object::Info.

Reimplemented from container::Container.

Reimplemented in container::ArrayList, container::LinkedList, container::OrderedArrayList, container::OrderedLinkedList, container::OrderedList, container::SortedArrayList, container::SortedLinkedList, and container::SortedList.

                                       {
   return TYPE_INFO;
}

Here is the caller graph for this function:

---

Member Data Documentation

const int container::List::NO_MATCHING_ENTITY_INDEX_FLAG = -1 [static]

Returned as an index value by method locateEntity() when a matching entity was not found in the list.

const Object::Info *const container::List::TYPE_INFO = Object::typeInfoFactory("List") [static]

Reimplemented from container::Container.

Reimplemented in container::ArrayList, container::LinkedList, container::OrderedArrayList, container::OrderedLinkedList, container::OrderedList, container::SortedArrayList, container::SortedLinkedList, and container::SortedList.

---

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

• list.h
• list.cpp