2.10.1 Constructors

These functions initialize traversers. A traverser must be initialized with one of these functions before it is passed to any other traverser function.

13. <Traverser constructor function prototypes 13> =
/* Table traverser functions. */
void tbl_t_init (struct tbl_traverser *, struct tbl_table *);
void *tbl_t_first (struct tbl_traverser *, struct tbl_table *);
void *tbl_t_last (struct tbl_traverser *, struct tbl_table *);
void *tbl_t_find (struct tbl_traverser *, struct tbl_table *, void *);
void *tbl_t_insert (struct tbl_traverser *, struct tbl_table *, void *);
void *tbl_t_copy (struct tbl_traverser *, const struct tbl_traverser *);

This code is included in 16.

All of these functions take a traverser to initialize as their first argument, and most take a table to associate the traverser with as their second argument. These arguments are here called trav and table. All, except tbl_t_init(), return the item to which trav is initialized, using a null pointer to represent the null item. None of the arguments to these functions may ever be a null pointer.

• tbl_t_init(): Initializes trav to the null item in table.
• tbl_t_first(): Initializes trav to the least-valued item in table. If the table is empty, then trav is initialized to the null item.
• tbl_t_last(): Same as tbl_t_first(), for the greatest-valued item in table.
• tbl_t_find(): Searches table for an item matching the one given. If one is found, initializes trav with it. If none is found, initializes trav to the null item.
• tbl_t_insert(): Attempts to insert the given item into table. If it is inserted succesfully, trav is initialized to its location. If it cannot be inserted because of a duplicate, the duplicate item is set as trav's current item. If there is a memory allocation error, trav is initialized to the null item.
• tbl_t_copy(): Initializes trav to the same table and item as a second valid traverser. Both arguments pointing to the same valid traverser is valid and causes no change in either.