2.10.2 Manipulators [ToC] [Index]     [Skip Back]     [Prev] [Up] [Next]

These functions manipulate valid traversers.

13. <Traverser manipulator function prototypes 13> =
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 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.

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

trav-circ.png

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:

[Click here for plain-text rendering]

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.