2.10.2 Manipulators |

These functions manipulate valid traversers.

13. <Traverser manipulator function prototypes 13> =void*tbl_t_next(structtbl_traverser*);void*tbl_t_prev(structtbl_traverser*);void*tbl_t_cur(structtbl_traverser*);void*tbl_t_replace(structtbl_traverser*,void*);

This code is included in 15.

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.