op_prg_list_size()
Abstract
Obtains the length of the specified list (i.e., the number of elements that the list contains).
Note: This KP is a macro call included for backward compatibility only. Use prg_list_size() in new code.
Syntax
op_prg_list_size (list_ptr)
| Argument | Type | Description |
|---|---|---|
list_ptr |
List* |
pointer to the list-of-interest A pointer to a list can be obtained from several KPs: an empty list can be obtained from op_prg_list_create(); a list representing the contents of a file can be obtained from op_prg_gdf_read(); a list can be allocated by user code, and initialized via op_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.]
Example
/* open and read in the contents of a GDF file */
list_ptr = op_prg_gdf_read (gdf_file_name);
/* loop through the contents of the GDF contents list, */
/* printing each line */
list_size = op_prg_list_size (list_ptr);
for (i = 0; i < list_size; i++)
printf ("line %d: [%s]\n", i, (char*) op_prg_list_access (list_ptr, i));
/* deallocate the elements on the list */
op_prg_list_free (list_ptr);
/* deallocate the list itself */
op_prg_mem_free (list_ptr);
Details
When a list is created via the KP op_prg_list_create(), or initialized via the KP op_prg_list_init(), it is empty, with a size of zero. As elements are inserted into a list via the KP op_prg_list_insert(), the list size increases by one with each insertion. As elements are removed from a list via the KP op_prg_list_remove(), the list size decreases by one with each removal.
Note: This KP 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 the KP op_prg_list_access()), or consumed and processed (via the KP op_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 KP. 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 the KP op_prg_list_insert() to insert a new element into a list
- Use the KP op_prg_list_remove() to remove an element from a list
- Use the KP op_prg_list_access() to obtain the address of a list element without removing it