#include <UtlList.h>

Inheritance diagram for UtlList:

[legend]

Collaboration diagram for UtlList:

Public Member Functions
virtual	~UtlList ()

UtlContainable *	get ()

UtlContainable *	removeReference (const UtlContainable *obj)

virtual UtlContainable *	remove (const UtlContainable *object)=0

UtlContainable *	removeAt (const size_t N)

virtual UtlBoolean	destroy (UtlContainable *)

void	destroyAll ()

void	removeAll ()

void	rehash ()

virtual UtlContainable *	find (const UtlContainable *) const =0

virtual UtlContainable *	at (size_t N) const

virtual UtlContainable *	first () const

virtual UtlContainable *	last () const

virtual size_t	entries () const

virtual UtlBoolean	isEmpty () const

virtual UtlBoolean	contains (const UtlContainable *object) const

virtual UtlBoolean	containsReference (const UtlContainable *) const

virtual size_t	occurrencesOf (const UtlContainable *obj) const =0

virtual size_t	index (const UtlContainable *obj) const =0

virtual UtlContainableType	getContainableType () const

Public Member Functions inherited from UtlContainer
	UtlContainer ()

virtual	~UtlContainer ()

virtual UtlContainable *	insert (UtlContainable *obj)=0

virtual unsigned	hash () const

virtual int	compareTo (const UtlContainable *otherObject) const

Public Member Functions inherited from UtlContainable
virtual	~UtlContainable ()

unsigned	directHash () const
	Provides a hash function that uses the object pointer as the hash value. More...

virtual UtlBoolean	isEqual (UtlContainable const *) const
	Test this object to another object for equality. More...

virtual UtlBoolean	isInstanceOf (const UtlContainableType type) const
	Determine if this object is a derivative of the specified UtlContainableType. More...

Public Member Functions inherited from UtlChain
	UtlChain ()
	Constructor initializes to unlinked. More...

	~UtlChain ()
	Destructor. More...

Static Public Attributes
static UtlContainableType	TYPE = "UtlList"

Static Public Attributes inherited from UtlContainer
static const UtlContainableType	TYPE = "UtlContainer"

Static Public Attributes inherited from UtlContainable
static const UtlContainableType	TYPE = "UtlContainable"

Protected Member Functions
	UtlList ()

void	notifyIteratorsOfRemove (UtlLink *element)

virtual void	removeLink (UtlLink *toBeRemoved)

Protected Member Functions inherited from UtlContainer
void	addIterator (UtlIterator *newIterator) const
	Add an iterator to the list to be notified of changes to this container. More...

void	removeIterator (UtlIterator *existingIterator) const
	Called from iterator destructor to prevent further notices. More...

void	invalidateIterators ()
	Call the invalidate method on all iterators. More...

Protected Member Functions inherited from UtlChain
bool	isUnLinked () const
	Is this block not linked to anything? More...

void	unchain ()
	Take the link out of its chain. More...

void	chainBefore (UtlChain *existing)
	Insert a new UtlChain before existing. More...

void	chainAfter (UtlChain *existing)
	Insert a new UtlChain after existing.. More...

UtlChain *	listHead () const
	Returns the head (first) UtlLink on the list (or NULL if the list is empty). More...

UtlChain *	listTail () const
	Returns the tail (last) UtlLink on the list (or NULL if the list is empty). More...

UtlLink *	head () const
	Returns the head (first) UtlLink on the list (or NULL if the list is empty). More...

UtlLink *	tail () const
	Returns the tail (last) UtlLink on the list (or NULL if the list is empty). More...

void	listBefore (UtlChain list, UtlChain existing)
	Insert this link into a list before an existing entry (before NULL == at the tail). More...

void	listAfter (UtlChain list, UtlChain existing)
	Insert this link into a list after an existing entry (after NULL == at the head). More...

UtlChain *	detachFromList (UtlChain *listHead)
	Remove a link from a list. More...

Friends
class	UtlListIterator

Additional Inherited Members
Static Public Member Functions inherited from UtlContainer
static void	acquireIteratorConnectionLock ()
	Lock the linkage between containers and iterators. More...

static void	releaseIteratorConnectionLock ()
	Unlock the linkage between containers and iterators. More...

Static Public Member Functions inherited from UtlContainable
static unsigned	stringHash (char const *value)
	Provides a hash function appropriate for null-terminated string values. More...

static UtlBoolean	areSameTypes (const UtlContainableType type1, const UtlContainableType type2)
	Are UtlContainable types the same. More...

Protected Attributes inherited from UtlContainer
OsBSem	mContainerLock
	Must be taken when making any change to container state. More...

UtlChain	mIteratorList

Protected Attributes inherited from UtlChain
UtlChain *	prev
	backward chain pointer More...

UtlChain *	next
	forward chain pointer More...

Detailed Description

UtlList is an abstract base class for list classes designed to contain any number of objects derived from the UtlContainable class. Like any UtlContainer, a UtlList may contain objects of different UtlContainableType (e.g. UtlInts and UtlVoidPtrs), however, sorting and comparison behavior may be non-obvious or undefined, so this is not recommended.

Most list accessors and inquiry methods are performed by equality as opposed to by reference. That is, the comparisons between UtlContainable objects are made using the UtlContainable::isEqual or UtlContainable::compareTo methods, so for example, two different UtlInt* values (having different pointer values) would compare as equal if they both contained the same integer value.

Some methods are concerned with references; these compare the actual UtlContainable* pointer values, so for example list.containsReference(obj) call will search for a pointer match with each UtlContainable* on the list, matching only when the value of the 'obj' pointer is found.

See also: UtlContainable for the methods that must be implemented by a class for its objects to be stored in any UtlContainer.

Like other UtlContainer classes, UtlList is itself a UtlContainable, so one can have lists of lists and other complex structures.

Constructor & Destructor Documentation

~UtlList ( )

virtual

< Class type used for runtime checking

UtlList ( )

protected

The UtlList constructor is protected - only subclasses may be instantiated

Member Function Documentation

UtlContainable * get ( )

Removes and returns the first item in the list (pop).

Returns: the first object if successful, otherwise null

UtlContainable * removeReference ( const UtlContainable * obj )

virtual

Remove the designated object by reference (as opposed to searching for an equality match).

Returns: the object if successful, otherwise null

Implements UtlContainer.

virtual UtlContainable* remove ( const UtlContainable * object )

pure virtual

Remove the designated object by equality (as opposed to by reference).

Implemented in UtlSList, and UtlSortedList.

UtlContainable * removeAt ( const size_t N )

Remove the object at (zero-based) location N.

Returns: the object removed from the list, or NULL if there was no object at index N

UtlBoolean destroy ( UtlContainable * obj )

virtual

Removes the designated objects from the list and frees the object by calling delete.

Implements UtlContainer.

Reimplemented in UtlSList.

void destroyAll ( )

virtual

Removes all elements from the list and deletes each one.

Implements UtlContainer.

void removeAll ( )

virtual

Removes all elements from the list without freeing the objects.

Implements UtlContainer.

void rehash ( )

Re-calculates hashes for all items

virtual UtlContainable* find ( const UtlContainable * ) const

pure virtual

Find the first occurence of the designated object by equality (as opposed to by reference).

Implements UtlContainer.

Implemented in UtlSList, and UtlSortedList.

UtlContainable * at ( size_t N ) const

virtual

Return the element at position N or null if N is out of bounds.

UtlContainable * first ( ) const

virtual

Return the first element (head) of the list

UtlContainable * last ( ) const

virtual

Return the last element (tail) of the list

size_t entries ( ) const

virtual

Return the total number of elements within the container

Implements UtlContainer.

UtlBoolean isEmpty ( void ) const

virtual

Return true of the container is empty (entries() == 0), otherwise false.

Implements UtlContainer.

UtlBoolean contains ( const UtlContainable * object ) const

virtual

Return true if the container includes the designated object. Each element within the list is tested for equality against the designated object using the equals() method.

Implements UtlContainer.

UtlBoolean containsReference ( const UtlContainable * containableToMatch ) const

virtual

Return true if the list contains the designated object reference.

virtual size_t occurrencesOf ( const UtlContainable * obj ) const

pure virtual

Return the number of occurrences of the designated object

Implemented in UtlSList, and UtlSortedList.

virtual size_t index ( const UtlContainable * obj ) const

pure virtual

Return the list position of the designated object or UTL_NOT_FOUND if not found.

Implemented in UtlSList, and UtlSortedList.

UtlContainableType getContainableType ( ) const

virtual

Get the ContainableType for the list as a contained object.

Reimplemented from UtlContainer.

Reimplemented in UtlSList, UtlCopyableSList, UtlSortedList, UtlCopyableSortedList, OsContactList, and UtlDList.

void notifyIteratorsOfRemove ( UtlLink * element )

protected

notifyIteratorsOfRemove - called before removing any element in the collection

void removeLink ( UtlLink * toBeRemoved )

protectedvirtual

removeLink is used internally to manipulate the links.

:NOTE: the caller must hold the mContainerLock

This does not return a new value for the current list position; this is because it will call the <some-list-iterator>::removing method on the removed element, passing the new value. This means the that current position update is always done the same way no matter what routine did the removing.

Friends And Related Function Documentation

friend class UtlListIterator

friend

Member Data Documentation

const UtlContainableType TYPE = "UtlList"

static

Public Member Functions

Static Public Attributes

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation