A struct tbl_traverser is a table “traverser” that allows the items in a table to be examined. With a traverser, the items within a table can be enumerated in sorted ascending or descending order, starting from either end or from somewhere in the middle.
The user of the traverser declares its own instance of struct tbl_traverser, typically as a local variable. One of the traverser constructor functions described below can be used to initialize it. Until then, the traverser is invalid. An invalid traverser must not be passed to any traverser function other than a constructor.
Seen from the viewpoint of a table user, a traverser has only one attribute: the current item. The current item is either an item in the table or the “null item”, represented by a null pointer and not associated with any item.
Traversers continue to work when their tables are modified. Any number of insertions and deletions may occur in the table without affecting the current item selected by a traverser, with only a few exceptions:
There is no need to destroy a traverser that is no longer needed. An unneeded traverser can simply be abandoned.