Microsoft DirectX 8.0 |
Implements an abtract list. The CGenericList class template, which derives from CBaseList, provides type checking and a simpler API than the CBaseList class.
Declaration: Wxlist.h
The CBaseList class is modeled after the CObList class in the Microsoft® Foundation Classes (MFC) library. Positions within the list are represented by a POSITION structure. The caller should not access the internal members of the POSITION structure; treat it as a pointer to a list node. The position of an object in the list remains valid until the object is deleted.
The list does not require any support by the objects it contains. It performs no storage management or copying on the objects. Objects can be in multiple lists.
Roughly half of the methods in this class act on single objects. These methods have the suffix -I in the method name. The other methods act on entire lists. For example, the AddAfter method appends a list to another list. Single-object operations return POSITION values, or NULL on failure. List operations return TRUE if successful or FALSE otherwise.
Protected Member Variables | |
---|---|
m_Count | Number of items in the list. |
m_pFirst | Pointer to the first node in the list. |
m_pLast | Pointer to the last node in the list. |
Protected Methods | |
GetNextI | Retrieves the item at the specified position, and advances the position. |
GetI | Retrieves the item at the specified position. |
FindI | Retrieves the first position that holds the specified item. |
RemoveHeadI | Removes the first item in the list. |
RemoveTailI | Removes the last item in the list. |
RemoveI | Removes the item at the specified position. |
AddTailI | Adds an item to the end of the list. |
AddHeadI | Adds an item to the front of the list. |
AddAfterI | Inserts an item after the specified position. |
AddBeforeI | Inserts an item before the specified position. |
Public Methods | |
CBaseList | Constructor method. |
~CBaseList | Destructor method. |
RemoveAll | Removes all nodes from the list. |
GetHeadPositionI | Retrieves the position of the first item in the list. |
GetTailPositionI | Retrieves the position of the last item of the list. |
GetCountI | Retrieves the number of items in the list. |
Next | Retrieves the next position in the list. |
Prev | Retrieves the previous position in the list. |
AddHead | Inserts another list at the front of this list. |
AddTail | Appends another list to the end of this list. |
AddAfter | Inserts a list after the specified position. |
AddBefore | Inserts a list before the specified position. |
MoveToTail | Splits the list and appends the head portion to the tail of another list. |
MoveToHead | Splits the list and inserts the tail portion at the head of another list. |
Reverse | Reverses the order of the list. |
Number of items in the list.
Syntax
LONG m_Count;
Pointer to the first node in the list.
Syntax
CNode *m_pFirst;
Pointer to the last node in the list.
Syntax
CNode *m_pLast;
Inserts a list after the specified position.
Syntax
BOOL AddAfter( POSITION pos, CBaseList *pList );
Parameters
- pos
- Position after which to insert the list.
- pList
- Pointer to the list to insert.
Return Value
Returns TRUE if successful, or FALSE otherwise.
Return Remarks
Existing position indicators, including the one specified in the pos parameter, remain valid. If the method fails, some of the items might have been added.
Inserts an item after the specified position.
Syntax
POSITION AddAfterI( POSITION pos, void *pObj );
Parameters
- pos
- Position after which to add the item.
- pObj
- Pointer to the item to add.
Return Value
Returns the position indicator of the inserted item.
Remarks
If pos is NULL, this method adds the item to the head of the list (equivalent to calling the AddHeadI method.)
Inserts a list before the specified position.
Syntax
BOOL AddBefore( POSITION pos, CBaseList *pList );
Parameters
- pos
- Position before which to insert the list.
- pList
- Pointer to the list to insert.
Return Value
Returns TRUE if successful. Otherwise, returns FALSE.
Remarks
Existing position indicators, including the one specified in the pos parameter, remain valid. If the method fails, some of the items might have been added.
Inserts an item before the specified position.
Syntax
POSITION AddBeforeI( POSITION pos, void *pObj );
Parameters
- pos
- Position before which to add the item.
- pObj
- Pointer to the item.
Return Value
Returns the position indicator for the inserted item.
Remarks
If pos is NULL, this method adds the item to the tail of the list (equivalent to calling the AddTailI method).
Inserts another list at the front of this list.
Syntax
BOOL AddHead( CBaseList *pList );
Parameters
- pList
- Pointer to the list of items to add.
Return Value
Returns TRUE if successful, or FALSE otherwise.
Remarks
If the method fails, some items might have been added to the list.
Adds an item to the front of the list.
Syntax
POSITION AddHeadI( void *pObj );
Parameters
- pObj
- Pointer to the item.
Return Value
Returns a POSITION value indicating the new head position.
Remarks
If the method fails, the return value is NULL.
Appends another list to the end of this list.
Syntax
BOOL AddTail( CBaseList *pList );
Parameters
- pList
- Pointer to the list to append.
Return Value
Returns TRUE if successful, or FALSE otherwise.
Remarks
If the method fails, some items may have been added to the list.
Adds an item to the end of the list.
Syntax
POSITION AddTailI( void *pObj );
Parameters
- pObj
- Pointer to the item.
Return Value
Returns a POSITION value for the new tail position.
Remarks
If the method fails, it returns NULL.
Constructor method.
Syntax
CBaseList( TCHAR *pName, INT iItems ); CBaseList( TCHAR *pName );
Parameters
- pName
- Pointer to the name of the list.
- iItems
- Size of the node cache.
Remarks
For efficiency, the CBaseList class maintains a cache of list nodes. If you know approximately how many items the list will hold, use the first version of the constructor. The second version uses a default cache size.
Destructor method.
Syntax
~CBaseList(void);
Retrieves the first position that holds the specified item.
Syntax
POSITION FindI( void *pObj );
Parameters
- pObj
- Pointer to the item.
Return Value
Returns a POSITION value, or NULL if the item is not in the list.
Retrieves the number of items in the list.
Syntax
int GetCountI(void);
Return Value
Returns the number of items in the list.
Retrieves the position of the first item in the list.
Syntax
POSITION GetHeadPositionI(void);
Return Value
Returns a POSITION value, or NULL if the list is empty.
Retrieves the item at the specified position.
Syntax
void *GetI( POSITION pos );
Parameters
- pos
- Position indicator for the item to retrieve.
Return Value
Returns a pointer to the item.
Remarks
If pos is NULL, the method returns NULL.
Retrieves the item at the specified position, and advances the position.
Syntax
void *GetNextI( POSITION& rp );
Parameters
- rp
- Reference to a POSITION value.
Return Value
Returns a pointer to the item.
Remarks
This method advances the position indicator to the next position. If the position indicator moves past the end of the list, the method sets it to NULL.
If rp is NULL, the method returns NULL.
Retrieves the position of the last item of the list.
Syntax
POSITION GetTailPositionI(void);
Return Value
Returns a POSITION value, or NULL if the list is empty.
Splits the list and inserts the tail portion at the head of another list.
Syntax
BOOL MoveToHead( POSITION pos, CBaseList *pList );
Parameters
- pos
- Position indicator that marks the split in the list.
- pList
- Pointer to another list.
Return Value
Returns TRUE if successful, or FALSE otherwise.
Remarks
This method splits the list before the position specified by the pos parameter. The head portion remains in the list. The tail portion is inserted at the head of the other list.
Splits the list and appends the head portion to the tail of another list.
Syntax
BOOL MoveToTail( POSITION pos, CBaseList *pList );
Parameters
- pos
- Position indicator that marks the split in the list.
- pList
- Pointer to another list.
Return Value
Returns TRUE if successful, or FALSE otherwise.
Remarks
This method splits the list after the position specified by the pos parameter. The tail portion remains in the list. The head portion is appended to the tail of the other list.
Retrieves the next position in the list.
Syntax
POSITION Next( POSITION pos );
Parameters
- pos
- POSITION value.
Return Value
Returns the position indicator that follows the position specified by pos.
Remarks
If pos is the last position in the list, the method returns NULL. If pos is NULL, the method returns the first position in the list.
Retrieves the previous position in the list.
Syntax
POSITION Prev( POSITION pos );
Parameters
- pos
- POSITION value.
Return Value
Returns the position indicator that is previous to the position specified in pos.
Remarks
If pos is the first position in the list, the method returns NULL. If pos is NULL, the method returns the last position in the list.
Removes all the nodes from the list.
Syntax
void RemoveAll(void);
Remarks
It is the caller's responsibility to delete the items contained in all the nodes.
Removes the first item in the list.
Syntax
void *RemoveHeadI(void);
Return Value
Returns a pointer to the item, or NULL if the list is empty.
Remarks
This method deletes the list node, but not the item that the node contains.
Removes the item at the specified position.
Syntax
void *RemoveI( POSITION pos );
Parameters
- pos
- POSITION value indicating the item to remove.
Return Value
Returns a pointer to the item.
Remarks
This method deletes the node from the list, but does not delete the item contained in that node.
If pos is NULL, the method returns NULL.
Removes the last item in the list.
Syntax
void *RemoveTailI(void);
Return Value
Returns a pointer to the item, or NULL if the list is empty.
Remarks
This method deletes the list node, but not the item that is contained in the node.
Reverses the order of the list.
Syntax
void Reverse(void);