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
| Name | Description |
| m_pFirst | Pointer to the first node in the list. |
| m_pLast | Pointer to the last node in the list. |
| m_Count | Number of nodes in the list. |
Member Functions
| Name | Description |
| 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 | Returns the first position that holds the specified object. |
| GetCountI | Returns the number of objects in the list. |
| GetHeadPositionI | Returns a cursor identifying the first element of the list. |
| GetI | Returns the object at the specified position. |
| GetNextI | Returns the specified object and updates the position. |
| GetTailPositionI | Returns 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 | Returns the next position in the list. |
| Prev | Returns 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. |
Inserts a list of nodes after the specified node.
BOOL AddAfter(
POSITION pos,
CBaseList *pList
);
Returns TRUE if successful; otherwise, returns FALSE.
Inserts a node after the specified node.
POSITION AddAfterI(
POSITION pos,
void * pObj
);
Returns the position of the inserted object.
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)
Inserts a list of nodes before the specified node.
BOOL AddBefore(
POSITION pos,
CBaseList *pList
);
Returns TRUE if successful; otherwise, returns FALSE.
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.
Inserts a node before the specified node.
POSITION AddBeforeI(
POSITION pos,
void * pObj
);
Returns the position of the inserted object.
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)
Inserts a list of nodes at the front of the list.
BOOL AddHead(
CBaseList *pList
);
No return value.
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.
Inserts a node at the front of the list.
POSITION AddHeadI(
void * pObj
);
Returns the new head position, or NULL if it fails. For list insertions, returns TRUE if successful; otherwise, returns FALSE.
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.
Appends a list of nodes to the end of the list.
BOOL AddTail(
CBaseList *pList
);
No return value.
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.
Appends a single node to the end of the list.
POSITION AddTailI(
void * pObj
);
Returns the new tail position, if successful; otherwise, returns NULL.
Constructs a CBaseList object.
CBaseList(
TCHAR *pName,
INT iItems
);
CBaseList(
TCHAR *pName
);
No return value.
Retrieves the first position that holds the specified object.
POSITION FindI(
void * pObj
);
Returns a position cursor.
A position cursor identifies an element on the list. Use the CBaseList::GetI member function to return the object at this position.
Retrieves the number of objects (object count) in the list.
int GetCountI( );
Returns the number of objects in the list.
Retrieves a cursor identifying the first element of the list.
POSITION GetHeadPositionI( );
Returns a position cursor.
A position cursor represents an element on the list. It is defined as a pointer to a void.
Retrieves the object at the specified position.
void *GetI(
POSITION pos
);
Returns a pointer to the object as position pos.
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.
Retrieves the specified object and updates the position.
void *GetNextI(
POSITION& rp
);
Returns a pointer to an object at the next position.
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.
Retrieves a cursor identifying the last element of the list.
POSITION GetTailPositionI( );
Returns a position cursor.
A position cursor represents an element on the list. A position is defined as a pointer to a void.
Moves the node or list of nodes to the beginning of a second list.
BOOL MoveToHead(
POSITION pos,
CBaseList *pList
);
Returns TRUE if successful; otherwise, returns FALSE.
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.
Moves the node or list of nodes to the end of a second list.
BOOL MoveToTail(
POSITION pos,
CBaseList *pList
);
Returns TRUE if successful; otherwise, returns FALSE.
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.
Retrieves the next position in the list.
POSITION Next(
POSITION pos
);
Returns a position cursor.
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.
Retrieves the previous position in the list.
POSITION Prev(
POSITION pos
);
Returns a position cursor.
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.
Removes all nodes from the list.
void RemoveAll( );
No return value.
Removes the first node in the list.
void *RemoveHeadI( );
Returns the pointer to the object that was removed.
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.
Removes the specified node from the list.
void *RemoveI(
POSITION pos
);
Returns the pointer to the object that was removed.
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.
Removes the last node in the list.
void *RemoveTailI( );
Returns the pointer to the object that was removed.
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.
Reverses the order of the pointers to the objects in the list.
void Reverse( );
No return value.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.