CBaseList Class

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_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

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.

---

CBaseList::AddAfter

CBaseList Class

Inserts a list of nodes after the specified node.

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 Values

Returns TRUE if successful; otherwise, returns FALSE.

---

CBaseList::AddAfterI

CBaseList Class

Inserts a node after the specified node.

POSITION AddAfterI(
  POSITION pos,
  void * pObj
  );

Parameters

pos

Position after which to add the node.

pObj

Pointer to the object to add.

Return Values

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.

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 Values

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.

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 Values

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.

BOOL AddHead(
  CBaseList *pList
  );

Parameters

pList

Pointer to the list of objects to add.

Return Values

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.

POSITION AddHeadI(
  void * pObj
  );

Parameters

pObj

Pointer to the object to add.

Return Values

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.

BOOL AddTail(
  CBaseList *pList
  );

Parameters

pList

Pointer to the list of objects to add.

Return Values

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.

POSITION AddTailI(
  void * pObj
  );

Parameters

pObj

Pointer to the object to add.

Return Values

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

---

CBaseList::CBaseList

CBaseList Class

Constructs a CBaseList object.

CBaseList(
  TCHAR *pName,
  INT iItems
  );

CBaseList(
  TCHAR *pName
  );

Parameters

pName

Name of the list.

iItems

Number of items in the list.

Return Values

No return value.

---

CBaseList::FindI

CBaseList Class

Retrieves the first position that holds the specified object.

POSITION FindI(
  void * pObj
  );

Parameters

pObj

Pointer to the object to find.

Return Values

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.

int GetCountI( );

Return Values

Returns the number of objects in the list.

---

CBaseList::GetHeadPositionI

CBaseList Class

Retrieves a cursor identifying the first element of the list.

POSITION GetHeadPositionI( );

Return Values

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.

void *GetI(
  POSITION pos
  );

Parameters

pos

Position in the list from which to retrieve the object.

Return Values

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.

void *GetNextI(
  POSITION& rp
  );

Parameters

rp

Returned pointer to the next object.

Return Values

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.

POSITION GetTailPositionI( );

Return Values

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.

BOOL MoveToHead(
  POSITION pos,
  CBaseList *pList
  );

Parameters

pos

Position that marks the split in the list.

pList

List in which to add the section of the list preceding the position passed in the pos parameter.

Return Values

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.

BOOL MoveToTail(
  POSITION pos,
  CBaseList *pList
  );

Parameters

pos

Position that marks the split in the list.

pList

List in which to add the section of the list specified in the pos parameter.

Return Values

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.

POSITION Next(
  POSITION pos
  );

Parameters

pos

Current position in the list.

Return Values

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.

POSITION Prev(
  POSITION pos
  );

Parameters

pos

Current position in the list.

Return Values

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.

void RemoveAll( );

Return Values

No return value.

---

CBaseList::RemoveHeadI

CBaseList Class

Removes the first node in the list.

void *RemoveHeadI( );

Return Values

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.

void *RemoveI(
  POSITION pos
  );

Parameters

pos

Position in the list of the node to remove.

Return Values

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.

void *RemoveTailI( );

Return Values

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.

void Reverse( );

Return Values

No return value.

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Top of Page