Microsoft DirectX 8.0

CBaseList Class

CBaseList class hierarchy

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_CountNumber of items in the list.
m_pFirstPointer to the first node in the list.
m_pLastPointer to the last node in the list.
Protected Methods
GetNextIRetrieves the item at the specified position, and advances the position.
GetIRetrieves the item at the specified position.
FindIRetrieves the first position that holds the specified item.
RemoveHeadIRemoves the first item in the list.
RemoveTailIRemoves the last item in the list.
RemoveIRemoves the item at the specified position.
AddTailIAdds an item to the end of the list.
AddHeadIAdds an item to the front of the list.
AddAfterIInserts an item after the specified position.
AddBeforeIInserts an item before the specified position.
Public Methods
CBaseListConstructor method.
~CBaseListDestructor method.
RemoveAllRemoves all nodes from the list.
GetHeadPositionIRetrieves the position of the first item in the list.
GetTailPositionIRetrieves the position of the last item of the list.
GetCountIRetrieves the number of items in the list.
NextRetrieves the next position in the list.
PrevRetrieves the previous position in the list.
AddHeadInserts another list at the front of this list.
AddTailAppends another list to the end of this list.
AddAfterInserts a list after the specified position.
AddBeforeInserts a list before the specified position.
MoveToTailSplits the list and appends the head portion to the tail of another list.
MoveToHeadSplits the list and inserts the tail portion at the head of another list.
ReverseReverses the order of the list.

CBaseList.m_Count

CBaseList Class

Number of items in the list.

Syntax

LONG m_Count;

CBaseList.m_pFirst

CBaseList Class

Pointer to the first node in the list.

Syntax

CNode *m_pFirst;

CBaseList.m_pLast

CBaseList Class

Pointer to the last node in the list.

Syntax

CNode *m_pLast;

CBaseList::AddAfter

CBaseList Class

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.

CBaseList::AddAfterI

CBaseList Class

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.)

CBaseList::AddBefore

CBaseList Class

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.

CBaseList::AddBeforeI

CBaseList Class

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).

CBaseList::AddHead

CBaseList Class

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.

CBaseList::AddHeadI

CBaseList Class

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.

CBaseList::AddTail

CBaseList Class

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.

CBaseList::AddTailI

CBaseList Class

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.

CBaseList::CBaseList

CBaseList Class

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.

CBaseList::~CBaseList

CBaseList Class

Destructor method.

Syntax

~CBaseList(void);

CBaseList::FindI

CBaseList Class

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.

CBaseList::GetCountI

CBaseList Class

Retrieves the number of items in the list.

Syntax

int GetCountI(void);

Return Value

Returns the number of items in the list.

CBaseList::GetHeadPositionI

CBaseList Class

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.

CBaseList::GetI

CBaseList Class

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.

CBaseList::GetNextI

CBaseList Class

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.

CBaseList::GetTailPositionI

CBaseList Class

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.

CBaseList::MoveToHead

CBaseList Class

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.

CBaseList::MoveToTail

CBaseList Class

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.

CBaseList::Next

CBaseList Class

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.

CBaseList::Prev

CBaseList Class

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.

CBaseList::RemoveAll

CBaseList Class

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.

CBaseList::RemoveHeadI

CBaseList Class

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.

CBaseList::RemoveI

CBaseList Class

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.

CBaseList::RemoveTailI

CBaseList Class

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.

CBaseList::Reverse

CBaseList Class

Reverses the order of the list.

Syntax

void Reverse(void);