prg_list_size()
Abstract
Obtains the length of the specified list (i.e., the number of elements that the list contains).
Syntax
prg_list_size (list_ptr)
| 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 obtained from prg_list_create(); a list representing the contents of a file can be obtained from prg_gdf_read(); a list can be allocated by user code and initialized via prg_list_init(). |
Return Type
int
Size of the specified list (i.e., number of element addresses stored in the list). An empty list has a size of zero.
Header
prg_list_funcs.h
Example:
/* open and read in the contents of a GDF file */
list_ptr = prg_gdf_read (gdf_file_name);
/* loop through the contents of the GDF contents list, */
/* printing each line */
list_size = prg_list_size (list_ptr);
for (i = 0; i < list_size; i++)
printf ("line %d: [%s]\n", i, (char*) prg_list_access (list_ptr, i));
/* deallocate the elements on the list */
prg_list_free (list_ptr);
/* deallocate the list itself */
prg_mem_free (list_ptr);
Details
When a list is created via prg_list_create(), or initialized via prg_list_init(), it is empty, with a size of zero. As elements are inserted into a list via prg_list_insert(), the list size increases by one with each insertion. As elements are removed from a list via prg_list_remove(), the list size decreases by one with each removal.
WARNING: This function is MT unsafe, as described in “Multi-Threading Safety“ on page 11. Access to shared lists must be externally serialized.
Purpose:
Provides a mechanism for determining the number of elements contained within a list. Typically this is useful when a list is to be sequentially scanned (via prg_list_access()), or consumed and processed (via prg_list_remove()). List scanning or processing can be implemented by constructing a loop which is executed once for every element in the list, as indicated by this function. The loop index value can serve as a position index in the case of list scanning, where the list size does not change as the loop progresses.
Errors:
- Program Abort: Segmentation violation. (due to invalid list pointer or malformed list)
Reference:
- use
prg_list_insert()to insert a new element into a list - use
prg_list_remove()to remove an element from a list - use
prg_list_access()to obtain the address of a list element without removing it