prg_list_clear()
Abstract
Removes the objects stored in a linked list and optionally deallocates them.
Syntax
prg_list_clear (list_ptr, dealloc_proc)
| Argument | Type | Description |
|---|---|---|
list_ptr |
PrgT_List * |
pointer to the list-of-interest. A pointer to a list can be obtained from several functions: an empty list can be originally obtained from prg_list_create(), a list representing the contents of a file can be obtained from prg_gdf_read(), or a list can be allocated by user code and initialized via prg_list_init(). |
dealloc_proc |
PrgT_List_Dealloc_Proc |
Procedure used to deallocate memory. |
Return Type
void
No return value.
Header
prg_list_funcs.h
Details
This function removes the elements from a list and optionally deallocates them. After calling this function, the list will be reinitialized with a size of 0. If dealloc_proc is PRGC_NIL, the elements are not deallocated. With a dealloc_proc specified, this function both removes and deallocates the elements of the list. If dealloc_proc is prg_mem_free(), this function works identically to prg_list_free().
The prototype for dealloc_proc is given in PrgT_List_Dealloc_Proc.
WARNING: This function is MT unsafe, as described in “Multi-Threading Safety“ on page 11. Access to shared lists must be externally serialized.
Reference:
- use
prg_list_free()to remove and deallocate the elements of a list if the elements were allocated using standard Program Library methods - use
prg_list_destroy()to destroy a list, including the list infrastructure, and optionally the items in the list - use
prg_mem_free()to deallocate the memory used by a list