liblist

Purpose

liblist provides a simple abstraction around doubly-linked lists. The following are the basic and common arguments for the use of any such library:

• A client program needs not reimplement such a common algorithm.
• Sharing well-tested and proven code eliminates one source of failure or mistake-making.
• Using an API's functions generally results in cleaner and clearer code than directly manipulating members of data structures.

API

liblist's public API is defined in list.h and List Traversal. A list handle is represented by the list_t typedef. This is initialized with list_init() and freed with list_free().

A list handle has a front, rear, and current element. The current element may be accessed with list_curr() and the other elements would be access with similarly named functions. Inserting new elements into the list causes the current element to refer to the newly inserted element. The current element pointer may also be changed with list_mvnext(), list_mvprev(), list_mvfirst(), and list_mvrear().

When updating or accessing a list, often operations are performed on the whole list at once or a search is done to find a certain element in the list. These operations may be performed using the basic list manipulation functions mentioned above. One may apply a function conforming to list_traverse_func_t to list elements using list_traverse(). The return value of this function can interrupt the traversal and the traversal can update the current element, making it useful for performing searches.

Alternate Paradigms

The doubly-linked list structure can easily be treated as if it supports the queue and stack paradigms. For example, restricting yourself to list_insert_before(), list_front(), and list_remove_front() lets the list behave as a stack. stack.h and queue.h provide macros to provide alternate interfaces.