2.10.2 Manipulators

These functions manipulate valid traversers.

14. <Traverser manipulator function prototypes 14> =
void *tbl_t_next (struct tbl_traverser *);
void *tbl_t_prev (struct tbl_traverser *);
void *tbl_t_cur (struct tbl_traverser *);
void *tbl_t_replace (struct tbl_traverser *, void *);

This code is included in 16.

Each of these functions takes a valid traverser, here called trav, as its first argument, and returns a data item. All but tbl_t_replace() can also return a null pointer that represents the null item. All arguments to these functions must be non-null pointers.

• tbl_t_next(): Advances trav to the next larger item in its table. If trav was at the null item in a nonempty table, then the smallest item in the table becomes current. If trav was already at the greatest item in its table or the table is empty, the null item becomes current. Returns the new current item.
• tbl_t_prev(): Advances trav to the next smaller item in its table. If trav was at the null item in a nonempty table, then the greatest item in the table becomes current. If trav was already at the lowest item in the table or the table is empty, the null item becomes current. Returns the new current item.
• tbl_t_cur(): Returns trav's current item.
• tbl_t_replace(): Replaces the data item currently selected in trav by the one provided. The replacement item is subject to the same restrictions as for the same replacement using tbl_probe(). The item replaced is returned. If the null item is current, the behavior is undefined.

Seen from the outside, the traverser treats the table as a circular arrangement of items:

Moving clockwise in the circle is equivalent, under our traverser, to moving to the next item with tbl_t_next(). Moving counterclockwise is equivalent to moving to the previous item with tbl_t_prev().

An equivalent view is that the traverser treats the table as a linear arrangement of nodes:

From this perspective, nodes are arranged from least to greatest in left to right order, and the null node lies in the middle as a connection between the least and greatest nodes. Moving to the next node is the same as moving to the right and moving to the previous node is motion to the left, except where the null node is concerned.