CBaseList Class

CBaseList class hierarchy

The CBaseList class represents a list of pointers to objects. No storage management or copying is done on the objects that are pointed to.

The implementation allows for objects to be on multiple lists simultaneously and does not require support in the objects themselves; therefore, it is particularly useful for holding variable-length lists of interface pointers.

The implementation is not multithread safe. External locks are required to maintain the integrity of the list when it is accessed from more than one thread simultaneously.

The POSITION structure represents a position in a linked list that is actually a void pointer. A position represents a cursor on the list that can be set to identify any element. NULL is a valid value, and several operations regard NULL as the position that is "one step off the end of the list." (In an n element list there are n+1 places to insert, and NULL is that n+1 value.) The position of an element in the list is only invalidated if that element is deleted. Move operations might indicate that what was a valid position in one list is now a valid position in a different list.

Some operations, which at first sight seem illegal, are allowed as harmless null operations (no-ops). For example, the CBaseList::RemoveHeadI member function is legal on an empty list, and it returns NULL. This allows an atomic way to test if there is an element there and, if so, to retrieve it.

Single-element operations return positions, where a non-NULL value indicates that it worked. Entire list operations return a Boolean value, where TRUE indicates success.

Protected Data Members

m_Count Number of nodes in the list.
m_pFirst Pointer to the first node in the list.
m_pLast Pointer to the last node in the list.

Member Functions

AddAfter Inserts a list of nodes after the specified node.
AddAfterI Inserts a node after the specified node.
AddBefore Inserts a list of nodes before the specified node.
AddBeforeI Inserts a node before the specified node.
AddHead Inserts a list of nodes at the front of the list.
AddHeadI Inserts a node at the front of the list.
AddTail Appends a list of nodes to the end of the list.
AddTailI Appends a node to the end of the list.
CBaseList Constructs a CBaseList object.
FindI Retrieves the first position that holds the specified object.
GetCountI Retrieves the number of objects in the list.
GetHeadPositionI Retrieves a cursor identifying the first element of the list.
GetI Retrieves the object at the specified position.
GetNextI Retrieves the specified object and updates the position.
GetTailPositionI Retrieves a cursor identifying the last element of the list.
MoveToHead Moves the node or list of nodes to the beginning of a second list.
MoveToTail Moves the node or list of nodes to the end of a second list.
Next Retrieves the next position in the list.
Prev Retrieves the previous position in the list.
RemoveAll Removes all nodes from the list.
RemoveHeadI Removes the first node in the list.
RemoveI Removes the specified node from the list.
RemoveTailI Removes the last node in the list.
Reverse Reverses the order of the pointers to the objects in the list.

CBaseList::AddAfter

CBaseList Class

Inserts a list of nodes after the specified node.

Syntax

BOOL AddAfter(
    POSITION pos,
    CBaseList *pList
    );

Parameters

pos
Position after which to add the list of nodes.
pList
Pointer to the list of objects to add.

Return Value

Returns TRUE if successful; otherwise, returns FALSE.

CBaseList::AddAfterI

CBaseList Class

Inserts a node after the specified node.

Syntax

POSITION AddAfterI(
    POSITION pos,
    void *pObj
    );

Parameters

pos
Position after which to add the node.
pObj
Pointer to the object to add.

Return Value

Returns the position of the inserted object.

Remarks

The following member function adds x to the start, which is equivalent to calling the CBaseList::AddHeadI member function.
AddAfterI(NULL,x)
If the list insertion fails, some of the elements might have been added. Existing positions in the list, including the position specified in the pos parameter, remain valid. The following two member functions are equivalent even in cases where pos is NULL or the Next(p) parameter is NULL. (This is similar for the mirror case.)
AddAfterI (p,x)
AddBeforeI(Next(p),x)

CBaseList::AddBefore

CBaseList Class

Inserts a list of nodes before the specified node.

Syntax

BOOL AddBefore(
    POSITION pos,
    CBaseList *pList
    );

Parameters

pos
Position before which to add the list of nodes.
pList
Pointer to the list of objects to add.

Return Value

Returns TRUE if successful; otherwise, returns FALSE.

Remarks

If the list insertion fails, some of the elements might have been added. Existing positions in the list, including the position specified in the pos parameter, remain valid.

CBaseList::AddBeforeI

CBaseList Class

Inserts a node before the specified node.

Syntax

POSITION AddBeforeI(
    POSITION pos,
    void *pObj
    );

Parameters

pos
Position before which to add the node or list of nodes.
pObj
Pointer to the object to add.

Return Value

Returns the position of the inserted object.

Remarks

The following member function adds the value specified in the x parameter to the end, which is equivalent to calling the CBaseList::AddTailI member function.
AddBeforeI(NULL,x)
The following two member functions are equivalent even in cases where pos is NULL or the Next(p) parameter is NULL. (This is similar for the mirror case.)
AddAfterI(p,x)
AddBeforeI(Next(p),x)

CBaseList::AddHead

CBaseList Class

Inserts a list of nodes at the front of the list.

Syntax

BOOL AddHead(
    CBaseList *pList
    );

Parameters

pList
Pointer to the list of objects to add.

Return Value

No return value.

Remarks

If you are adding Component Object Model (COM) objects, you might want to add references to them (using the IUnknown::AddRef method) first. Other existing positions in the list remain valid.
This member function duplicates all the nodes in the pList parameter (that is, duplicates all its pointers to objects). It does not duplicate the objects.

CBaseList::AddHeadI

CBaseList Class

Inserts a node at the front of the list.

Syntax

POSITION AddHeadI(
    void *pObj
    );

Parameters

pObj
Pointer to the object to add.

Return Value

Returns the new head position, or NULL if it fails. For list insertions, returns TRUE if successful; otherwise, returns FALSE.

Remarks

If you are adding Component Object Model (COM) objects, you might want to add references to them (using the IUnknown::AddRef method) first. Other existing positions in the list remain valid.

CBaseList::AddTail

CBaseList Class

Appends a list of nodes to the end of the list.

Syntax

BOOL AddTail(
    CBaseList *pList
    );

Parameters

pList
Pointer to the list of objects to add.

Return Value

No return value.

Remarks

This member function duplicates all the nodes in pList (that is, duplicates all its pointers to objects). It does not duplicate the objects. Existing positions in the list remain valid.

CBaseList::AddTailI

CBaseList Class

Appends a single node to the end of the list.

Syntax

POSITION AddTailI(
    void *pObj
    );

Parameters

pObj
Pointer to the object to add.

Return Value

Returns the new tail position, if successful; otherwise, returns NULL.

CBaseList::CBaseList

CBaseList Class

Constructs a CBaseList object.

Syntax

CBaseList(
    TCHAR *pName,
    INT iItems
    );

CBaseList(
    TCHAR *pName
    );

Parameters

pName
Pointer to the name of the list.
iItems
Number of items in the list.

Return Value

No return value.

Remarks

Use the first version of the constructor for increased performance, if you have some idea of the number of items the list will hold. The second version of the constructor preallocates space for 10 items.

CBaseList::FindI

CBaseList Class

Retrieves the first position that holds the specified object.

Syntax

POSITION FindI(
    void *pObj
    );

Parameters

pObj
Pointer to the object to find.

Return Value

Returns a position cursor.

Remarks

A position cursor identifies an element on the list. Use the CBaseList::GetI member function to return the object at this position.

CBaseList::GetCountI

CBaseList Class

Retrieves the number of objects (object count) in the list.

Syntax

int GetCountI(void);

Return Value

Returns the number of objects in the list.

CBaseList::GetHeadPositionI

CBaseList Class

Retrieves a cursor identifying the first element of the list.

Syntax

POSITION GetHeadPositionI(void);

Return Value

Returns a position cursor.

Remarks

A position cursor represents an element on the list. It is defined as a pointer to a void.

CBaseList::GetI

CBaseList Class

Retrieves the object at the specified position.

Syntax

void *GetI(
    POSITION pos
    );

Parameters

pos
Position in the list from which to retrieve the object.

Return Value

Returns a pointer to the object as position pos.

Remarks

Use the CBaseList::Next, CBaseList::Prev, or CBaseList::FindI member function to obtain the position. Asking for the object at a NULL position returns NULL without generating an error.

CBaseList::GetNextI

CBaseList Class

Retrieves the specified object and updates the position.

Syntax

void *GetNextI(
    POSITION& rp
    );

Parameters

rp
Returned pointer to the next object.

Return Value

Returns a pointer to an object at the next position.

Remarks

This member function updates the rp parameter to the next node in the list, but makes it NULL if it was at the end of the list.
This member function is retained only for backward compatibility. (GetPrev is not implemented.)
Use the CBaseList::Next and CBaseList::Prev member functions to access the next or previous object in the list.

CBaseList::GetTailPositionI

CBaseList Class

Retrieves a cursor identifying the last element of the list.

Syntax

POSITION GetTailPositionI(void);

Return Value

Returns a position cursor.

Remarks

A position cursor represents an element on the list. A position is defined as a pointer to a void.

CBaseList::MoveToHead

CBaseList Class

Moves the node or list of nodes to the beginning of a second list.

Syntax

BOOL MoveToHead(
    POSITION pos,
    CBaseList *pList
    );

Parameters

pos
Position that marks the split in the list.
pList
Pointer to the list in which to add the section of the list preceding the position passed in the pos parameter.

Return Value

Returns TRUE if successful; otherwise, returns FALSE.

Remarks

This member function splits the current list after the position specified in the pos parameter in the list and retains the head portion of the original list. It then adds the tail portion to the head of the second list, identified by the pList parameter.

CBaseList::MoveToTail

CBaseList Class

Moves the node or list of nodes to the end of a second list.

Syntax

BOOL MoveToTail(
    POSITION pos,
    CBaseList *pList
    );

Parameters

pos
Position that marks the split in the list.
pList
Pointer to the list in which to add the section of the list specified in the pos parameter.

Return Value

Returns TRUE if successful; otherwise, returns FALSE.

Remarks

This member function splits the current list after the position specified in the pos parameter in the list and retains the tail portion of the original list. It then adds the head portion to the tail end of the second list, using the pList parameter.

CBaseList::Next

CBaseList Class

Retrieves the next position in the list.

Syntax

POSITION Next(
    POSITION pos
    );

Parameters

pos
Current position in the list.

Return Value

Returns a position cursor.

Remarks

This member function returns NULL when going past the beginning of the list. Calling the CBaseList::Next member function with a null value is similar to calling the CBaseList::GetHeadPositionI member function.
Use the CBaseList::GetI member function to return the object at the returned position.

CBaseList::Prev

CBaseList Class

Retrieves the previous position in the list.

Syntax

POSITION Prev(
    POSITION pos
    );

Parameters

pos
Current position in the list.

Return Value

Returns a position cursor.

Remarks

This member function returns NULL when going past the end of the list. Calling the CBaseList::Prev member function with a null value is similar to calling the CBaseList::GetTailPositionI member function.
Use the CBaseList::GetI member function to return the object at the returned position.

CBaseList::RemoveAll

CBaseList Class

Removes all nodes from the list.

Syntax

void RemoveAll(void);

Return Value

No return value.

CBaseList::RemoveHeadI

CBaseList Class

Removes the first node in the list.

Syntax

void *RemoveHeadI(void);

Return Value

Returns the pointer to the object that was removed.

Remarks

This member function deletes the pointer to its object from the list, but does not free the object itself.
If the list was already empty, this member function harmlessly returns NULL.

CBaseList::RemoveI

CBaseList Class

Removes the specified node from the list.

Syntax

void *RemoveI(
    POSITION pos
    );

Parameters

pos
Position in the list of the node to remove.

Return Value

Returns the pointer to the object that was removed.

Remarks

This member function deletes the pointer to its object from the list, but does not free the object itself.
If the list was already empty, this member function harmlessly returns NULL.

CBaseList::RemoveTailI

CBaseList Class

Removes the last node in the list.

Syntax

void *RemoveTailI(void);

Return Value

Returns the pointer to the object that was removed.

Remarks

This member function deletes the pointer to its object from the list, but does not free the object.
If the list was already empty, this member function harmlessly returns NULL.

CBaseList::Reverse

CBaseList Class

Reverses the order of the pointers to the objects in the list.

Syntax

void Reverse(void);

Return Value

No return value.

m_Count	Number of nodes in the list.
m_pFirst	Pointer to the first node in the list.
m_pLast	Pointer to the last node in the list.

AddAfter	Inserts a list of nodes after the specified node.
AddAfterI	Inserts a node after the specified node.
AddBefore	Inserts a list of nodes before the specified node.
AddBeforeI	Inserts a node before the specified node.
AddHead	Inserts a list of nodes at the front of the list.
AddHeadI	Inserts a node at the front of the list.
AddTail	Appends a list of nodes to the end of the list.
AddTailI	Appends a node to the end of the list.
CBaseList	Constructs a CBaseList object.
FindI	Retrieves the first position that holds the specified object.
GetCountI	Retrieves the number of objects in the list.
GetHeadPositionI	Retrieves a cursor identifying the first element of the list.
GetI	Retrieves the object at the specified position.
GetNextI	Retrieves the specified object and updates the position.
GetTailPositionI	Retrieves a cursor identifying the last element of the list.
MoveToHead	Moves the node or list of nodes to the beginning of a second list.
MoveToTail	Moves the node or list of nodes to the end of a second list.
Next	Retrieves the next position in the list.
Prev	Retrieves the previous position in the list.
RemoveAll	Removes all nodes from the list.
RemoveHeadI	Removes the first node in the list.
RemoveI	Removes the specified node from the list.
RemoveTailI	Removes the last node in the list.
Reverse	Reverses the order of the pointers to the objects in the list.