Creation and Destruction - GNU libavl 2.0.3
Author: Ben Pfaff

2.6 Creation and Destruction |

This section describes the functions that create and destroy tables.

    9. <Table creation function prototypes 9> =
    /* 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 16.

- 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.