2.10 Traversers

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:

• Deleting a traverser's current item from its table invalidates the traverser (even if the item is later re-inserted).
• Using the return value of tbl_probe() to replace an item in the table invalidates all traversers with that item current, unless the replacement item has the same key data as the original item (that is, the table's comparison function returns 0 when the two items are compared).
• Similarly, tbl_t_replace() invalidates all other traversers with the same item selected, unless the replacement item has the same key data.
• Destroying a table with tbl_destroy() invalidates all of that table's traversers.

There is no need to destroy a traverser that is no longer needed. An unneeded traverser can simply be abandoned.