List entries may be created in one of two ways. The most common is to embed the NihList structure as the frist member of your own structure, and initialise it with nih_list_init() after allocating the structure. Alternatively you may create NihListEntry structures with nih_list_entry_new() and point at your own data from them.
The list head itself may be created with nih_list_new().
Entries are added to the list with nih_list_add(), passing an existing entry which is most commonly the list head. This adds the entry "before" the given entry, in the list head case this appends the entry to the list. To add "after" the given entry (prepending in the list head case) use nih_list_add_before().
Entries may be moved between lists, or rearranged within a list, by simply calling nih_list_add() - there's no need to call nih_list_remove() first.
List iteration may be performed by following the prev or next pointers in a for loop. Since this is an extremely common operation, the NIH_LIST_FOREACH() macro is provided that expands to this for loop.
Since this macro only holds a pointer to the entry being iterated, most operations that change a list are not safe. To change a list safely while iterating, including being able to free the visited node, use the NIH_LIST_FOREACH_SAFE() macro. However note that since this macro changes the list as it iterates it itself, it is not safe to traverse or iterate the list and make assumptions about the type of node being seen. NihList: : previous entry in the list, : next entry in the list.
This structure can be used both to refer to a linked list and can be placed in your own structures to use them as list entries.
|struct nih_list *||next|
|struct nih_list *||prev|