CObList Class

Note

The CObList class handles ordered lists of nonunique CObject pointers accessible sequentially or by pointer value

The structure used for this class is CObList

Quick Ref

void CObList::CObList(int nBlockSize)

virtual void CObList::~CObList()

POSITION* CObList::AddHead(CObArray* newElement)

POSITION* CObList::AddTail(CObArray* newElement)

POSITION* CObList::Find(CObArray* searchValue, POSITION* startAfter)

CObList::CNode* CObList::NewNode(CObList::CNode* pPrev, CObList::CNode* pNext)

void CObList::RemoveAll()

void CObList::RemoveAt(POSITION* position)

CObArray* CObList::RemoveHead()

Constructors

Name	Description
CObList::CObList	Constructs a `CObList` object
CObList::~CObList	Destroys a `CObList` object

CObList::CObList

Constructs a CObList object

void CObList::CObList(int nBlockSize);

Parameters

int nBlockSize - the memory-allocation granularity for extending the list

Remarks

Constructs a CObList object

As the list grows, memory is allocated in units of nBlockSize entries. If a memory allocation fails, a CMemoryException is thrown

CObList::~CObList

Destroys the CObList object

virtual void CObList::~CObList();

Remarks

Destroys the CObList object

Methods

Name	Description
CObList::AddHead	Adds an element to the head of the list
CObList::AddTail	Adds an element to the tail of the list
CObList::Find	Searches the list sequentially for matching specified pointer
CObList::NewNode	Creates a new node in the list
CObList::RemoveAll	Removes all the elements from this list
CObList::RemoveAt	Removes the specified element from this list
CObList::RemoveHead	Removes the element from the head of the list

CObList::AddHead

Adds an element (or all the elements in another list) to the head of the list (makes a new head)

POSITION* CObList::AddHead(CObArray* newElement);

Parameters

CObArray* newElement - the CObject pointer to be added to this list

Return Value

Returns POSITION*, the value of the newly inserted element

Remarks

The list can be empty before the operation

CObList::AddTail

Adds an element (or all the elements in another list) to the tail of the list (makes a new tail)

POSITION* CObList::AddTail(CObArray* newElement);

Parameters

CObArray* newElement - the CObject pointer to be added to this list

Return Value

The first version returns the POSITION value of the newly inserted element

Remarks

The list can be empty before the operation

CObList::Find

Searches the list sequentially to find the first CObject pointer matching the specified CObject pointer

POSITION* CObList::Find(
   CObArray* searchValue,
   POSITION* startAfter);

Parameters

CObArray* searchValue - the object pointer to be found in this list
POSITION* startAfter - the start position for the search

Return Value

A POSITION value that can be used for iteration or object pointer retrieval; NULL if the object is not found

Remarks

Note that the pointer values are compared, not the contents of the objects

CObList::NewNode

Creates a new node in the list

CObList::CNode* CObList::NewNode(
   CObList::CNode* pPrev,
   CObList::CNode* pNext);

Parameters

CObList::CNode* pPrev - pointer to previous node
CObList::CNode* pNext - pointer to next node

Return Value

Returns CObList::CNode*

Remarks

CObList::RemoveAll

Removes all the elements from this list and frees the associated CObList memory

void CObList::RemoveAll();

Remarks

No error is generated if the list is already empty.

When you remove elements from a CObList, you remove the object pointers from the list. It is your responsibility to delete the objects themselves.

CObList::RemoveAt

Removes the specified element from this list

void CObList::RemoveAt(POSITION* position);

Parameters

POSITION* position - The position of the element to be removed from the list

Remarks

When you remove an element from a CObList, you remove the object pointer from the list. It is your responsibility to delete the objects themselves.

You must ensure that your POSITION value represents a valid position in the list

CObList::RemoveHead

Removes the element from the head of the list and returns a pointer to it

CObArray* CObList::RemoveHead();

Return Value

Returns CObArray* - the CObject pointer previously at the head of the list

Remarks

You must ensure that the list is not empty before calling RemoveHead