www.delorie.com/gnu/docs/avl/libavl_15.html

search

	Buy GNU books!

GNU libavl 2.0.1

3.6 Creation and Destruction

This section describes the functions that create and destroy tables.

/* 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 @refalso{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.