2.6 Creation and Destruction

This section describes the functions that create and destroy tables.

8. <Table creation function prototypes 8> =
/* Table functions. */
struct tbl_table *tbl_create (tbl_comparison_func *, void *, 
                              struct libavl_allocator *);
struct tbl_table *tbl_copy (const struct tbl_table *, tbl_copy_func *,
                            tbl_item_func *, struct libavl_allocator *);
void tbl_destroy (struct tbl_table *, tbl_item_func *);

This code is included in 15.

• tbl_create(): Creates and returns a new, empty table as a struct tbl_table *. The table is associated with the given arguments. The void * argument is passed as the third argument to the comparison function when it is called. If the allocator is a null pointer, then tbl_allocator_default is used.
• tbl_destroy(): Destroys a table. During destruction, the tbl_item_func provided, if non-null, is called once for every item in the table, in no particular order. The function, if provided, must not invoke any table function or macro on the table being destroyed.
• tbl_copy(): Creates and returns a new table with the same contents as the existing table passed as its first argument. Its other three arguments may all be null pointers.

  If a tbl_copy_func is provided, then it is used to make a copy of each table item as it is inserted into the new table, in no particular order (a deep copy (see deep copy)). Otherwise, the void * table items are copied verbatim (a shallow copy (see shallow copy)).

  If the table copy fails, either due to memory allocation failure or a null pointer returned by the tbl_copy_func, tbl_copy() returns a null pointer. In this case, any provided tbl_item_func is called once for each new item already copied, in no particular order.

  By default, the new table uses the same memory allocator as the existing one. If non-null, the struct libavl_allocator * given is used instead as the new memory allocator. To use the tbl_allocator_default allocator, specify &tbl_allocator_default explicitly.