Mercurial > hg > ucx / file diff

--- 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 <code>NULL</code>, if this is the
+     * last element.
+     */
     UcxList *next;
+    /**
+     * Pointer to the previous list element or <code>NULL</code>, 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);
+
+/**
+ * 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);
 
-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);
+/**
+ * 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.
+ * 
+ * <b>Caution:</b> the argument <b>MUST</b> 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_sort(UcxList *l, cmp_func fnc, void *data);
+UcxList *ucx_list_sort(UcxList *list, cmp_func cmpfnc, void *data);
 
-UcxList *ucx_list_first(const UcxList *l);
-UcxList *ucx_list_remove(UcxList *l, UcxList *e);
+UcxList *ucx_list_first(const UcxList *list);
+UcxList *ucx_list_remove(UcxList *list, UcxList *element);
 
 #ifdef	__cplusplus
 }