diff -r 540d99722f1f -r 7fb0f74517c5 ucx/list.h
--- a/ucx/list.h Mon Jul 22 11:53:39 2013 +0200
+++ b/ucx/list.h Mon Jul 22 13:45:49 2013 +0200
@@ -25,6 +25,13 @@
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
*/
+/**
+ * Double linked list implementation.
+ *
+ * @file list.h
+ * @author Mike Becker
+ * @author Olaf Wintermann
+ */
#ifndef UCX_LIST_H
#define UCX_LIST_H
@@ -52,30 +59,77 @@
#define UCX_FOREACH(elem,list) \
for (UcxList* elem = list ; elem != NULL ; elem = elem->next)
+/**
+ * UCX list type
+ * @see UcxList
+ */
typedef struct UcxList UcxList;
struct UcxList {
+ /**
+ * List element payload.
+ */
void *data;
+ /**
+ * Pointer to the next list element or NULL
, if this is the
+ * last element.
+ */
UcxList *next;
+ /**
+ * Pointer to the previous list element or NULL
, if this is
+ * the first element.
+ */
UcxList *prev;
};
UcxList *ucx_list_clone(UcxList *l, copy_func fnc, void* data);
-int ucx_list_equals(const UcxList *l1, const UcxList *l2,
- cmp_func fnc, void* data);
-void ucx_list_free(UcxList *l);
-UcxList *ucx_list_append(UcxList *l, void *data);
-UcxList *ucx_list_prepend(UcxList *l, void *data);
-UcxList *ucx_list_concat(UcxList *l1, UcxList *l2);
-UcxList *ucx_list_last(const UcxList *l);
-UcxList *ucx_list_get(const UcxList *l, int index);
-size_t ucx_list_size(const UcxList *l);
-int ucx_list_contains(UcxList *l, void *elem, cmp_func fnc, void *cmpdata);
+/**
+ * Compares two UCX lists element-wise by using a compare function.
+ *
+ * Each element of the two specified lists are compared by using the specified
+ * compare function and the additional data. The type and content of this
+ * additional data depends on the cmp_func() used.
+ *
+ * If the list pointers denote elements within a list, the lists are compared
+ * starting with the denoted elements. Thus any previous elements are not taken
+ * into account. This might be useful to check, if certain list tails match
+ * each other.
+ *
+ * @param list1 the first list
+ * @param list2 the second list
+ * @param cmpfnc the compare function
+ * @param data additional data for the compare function
+ * @return 1, if and only if the two lists equal element-wise, 0 otherwise
+ */
+int ucx_list_equals(const UcxList *list1, const UcxList *list2,
+ cmp_func cmpfnc, void* data);
-UcxList *ucx_list_sort(UcxList *l, cmp_func fnc, void *data);
+/**
+ * Destroys the entire list.
+ *
+ * The members of the list are not automatically freed, so ensure they are
+ * otherwise referenced or a memory leak will occur.
+ *
+ * Caution: the argument MUST denote an entire list (i.e. a call
+ * to ucx_list_first() on the argument must return the argument itself)
+ *
+ * @param list The list to free.
+ */
+void ucx_list_free(UcxList *list);
+UcxList *ucx_list_append(UcxList *list, void *data);
+UcxList *ucx_list_prepend(UcxList *list, void *data);
+UcxList *ucx_list_concat(UcxList *list1, UcxList *list2);
+UcxList *ucx_list_last(const UcxList *list);
+UcxList *ucx_list_get(const UcxList *list, int index);
+ssize_t ucx_list_indexof(const UcxList *list, const UcxList *elem);
+size_t ucx_list_size(const UcxList *list);
+ssize_t ucx_list_find(UcxList *list, void *elem, cmp_func fnc, void *cmpdata);
+int ucx_list_contains(UcxList *list, void *elem, cmp_func fnc, void *cmpdata);
-UcxList *ucx_list_first(const UcxList *l);
-UcxList *ucx_list_remove(UcxList *l, UcxList *e);
+UcxList *ucx_list_sort(UcxList *list, cmp_func cmpfnc, void *data);
+
+UcxList *ucx_list_first(const UcxList *list);
+UcxList *ucx_list_remove(UcxList *list, UcxList *element);
#ifdef __cplusplus
}