Traversing a List

You can traverse a list equally quickly from front to back or from back to front. The following sections explain how.

Traversing a List From Front to Back

To traverse a list from front to back, use ScanList(). It iterates through all of the elements in the list.

Example 1: Traversing a list front to back.

ScanList(list,n,DataType)
{
    /* here you can dereference "n" */
}

ScanList() is a macro made up of the simpler macros FirstNode(), IsNode(), and NextNode().

Use FirstNode() to get the first node in a list:

Node *FirstNode( const List *l )

The l argument is a pointer to the list the node is in. The macro returns a pointer to the first node in the list or, if the list is empty, a pointer to the tail anchor.

To check to see if a node is an actual node rather than the tail anchor, use IsNode():

bool IsNode( const List *l, const Node *n )

The l argument is a pointer to the list containing the node; the n argument is a pointer to the node to check. The macro returns FALSE if it is the tail anchor or TRUE for any other node. (IsNode()returns TRUE for any node that is not the tail anchor, no matter if the node is in the specified list.)

To go from one node to its successor in the same list, use NextNode():

Node *NextNode( const Node *n )

The n argument is a pointer to the current node. (This node must be in a list.) The macro returns a pointer to the next node in the list or, if the current node is the last node in the list, to the tail anchor.

Traversing a List From Back to Front

To traverse a list from front to back, use the ScanListB() macro. It iterates through all the elements in the list.

Example 2: Traversing a list back to front.

ScanListB(list,n,DataType)
{
    /* here you can dereference "n" */
}

ScanListB() is a macro made up of the simpler macros LastNode(), IsNodeB(), and PrevNode().

Use LastNode() to get the last node in a list:

Node *LastNode( const List *l )

The l argument is a pointer to the list the node is in. The macro returns a pointer to the last node in the list or, if the list is empty, a pointer to the head anchor.

To check to see if a node is an actual node rather than the head anchor, use IsNodeB():

bool IsNodeB( const List *l, const Node *n )

The l argument is a pointer to the list containing the node to check; the n argument is a pointer to the node to check. The macro returns FALSE if it is the head anchor or TRUE for any other node. (The macro returns TRUE for any node that is not the head anchor, whether or not the node is in the specified list.)

To go from one node to its predeccessor in the list, use the PrevNode() macro:

Node *PrevNode( const Node *n )

The n argument is a pointer to the current node. (This node must be in a list.) The macro returns a pointer to the previous node in the list or, if the current node is the first node in the list, to the head anchor.