1.1 --- a/ucx/list.h Mon Jul 22 11:53:39 2013 +0200
1.2 +++ b/ucx/list.h Mon Jul 22 13:45:49 2013 +0200
1.3 @@ -25,6 +25,13 @@
1.4 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
1.5 * POSSIBILITY OF SUCH DAMAGE.
1.6 */
1.7 +/**
1.8 + * Double linked list implementation.
1.9 + *
1.10 + * @file list.h
1.11 + * @author Mike Becker
1.12 + * @author Olaf Wintermann
1.13 + */
1.14
1.15 #ifndef UCX_LIST_H
1.16 #define UCX_LIST_H
1.17 @@ -52,30 +59,77 @@
1.18 #define UCX_FOREACH(elem,list) \
1.19 for (UcxList* elem = list ; elem != NULL ; elem = elem->next)
1.20
1.21 +/**
1.22 + * UCX list type
1.23 + * @see UcxList
1.24 + */
1.25 typedef struct UcxList UcxList;
1.26 struct UcxList {
1.27 + /**
1.28 + * List element payload.
1.29 + */
1.30 void *data;
1.31 + /**
1.32 + * Pointer to the next list element or <code>NULL</code>, if this is the
1.33 + * last element.
1.34 + */
1.35 UcxList *next;
1.36 + /**
1.37 + * Pointer to the previous list element or <code>NULL</code>, if this is
1.38 + * the first element.
1.39 + */
1.40 UcxList *prev;
1.41 };
1.42
1.43 UcxList *ucx_list_clone(UcxList *l, copy_func fnc, void* data);
1.44 -int ucx_list_equals(const UcxList *l1, const UcxList *l2,
1.45 - cmp_func fnc, void* data);
1.46
1.47 -void ucx_list_free(UcxList *l);
1.48 -UcxList *ucx_list_append(UcxList *l, void *data);
1.49 -UcxList *ucx_list_prepend(UcxList *l, void *data);
1.50 -UcxList *ucx_list_concat(UcxList *l1, UcxList *l2);
1.51 -UcxList *ucx_list_last(const UcxList *l);
1.52 -UcxList *ucx_list_get(const UcxList *l, int index);
1.53 -size_t ucx_list_size(const UcxList *l);
1.54 -int ucx_list_contains(UcxList *l, void *elem, cmp_func fnc, void *cmpdata);
1.55 +/**
1.56 + * Compares two UCX lists element-wise by using a compare function.
1.57 + *
1.58 + * Each element of the two specified lists are compared by using the specified
1.59 + * compare function and the additional data. The type and content of this
1.60 + * additional data depends on the cmp_func() used.
1.61 + *
1.62 + * If the list pointers denote elements within a list, the lists are compared
1.63 + * starting with the denoted elements. Thus any previous elements are not taken
1.64 + * into account. This might be useful to check, if certain list tails match
1.65 + * each other.
1.66 + *
1.67 + * @param list1 the first list
1.68 + * @param list2 the second list
1.69 + * @param cmpfnc the compare function
1.70 + * @param data additional data for the compare function
1.71 + * @return 1, if and only if the two lists equal element-wise, 0 otherwise
1.72 + */
1.73 +int ucx_list_equals(const UcxList *list1, const UcxList *list2,
1.74 + cmp_func cmpfnc, void* data);
1.75
1.76 -UcxList *ucx_list_sort(UcxList *l, cmp_func fnc, void *data);
1.77 +/**
1.78 + * Destroys the entire list.
1.79 + *
1.80 + * The members of the list are not automatically freed, so ensure they are
1.81 + * otherwise referenced or a memory leak will occur.
1.82 + *
1.83 + * <b>Caution:</b> the argument <b>MUST</b> denote an entire list (i.e. a call
1.84 + * to ucx_list_first() on the argument must return the argument itself)
1.85 + *
1.86 + * @param list The list to free.
1.87 + */
1.88 +void ucx_list_free(UcxList *list);
1.89 +UcxList *ucx_list_append(UcxList *list, void *data);
1.90 +UcxList *ucx_list_prepend(UcxList *list, void *data);
1.91 +UcxList *ucx_list_concat(UcxList *list1, UcxList *list2);
1.92 +UcxList *ucx_list_last(const UcxList *list);
1.93 +UcxList *ucx_list_get(const UcxList *list, int index);
1.94 +ssize_t ucx_list_indexof(const UcxList *list, const UcxList *elem);
1.95 +size_t ucx_list_size(const UcxList *list);
1.96 +ssize_t ucx_list_find(UcxList *list, void *elem, cmp_func fnc, void *cmpdata);
1.97 +int ucx_list_contains(UcxList *list, void *elem, cmp_func fnc, void *cmpdata);
1.98
1.99 -UcxList *ucx_list_first(const UcxList *l);
1.100 -UcxList *ucx_list_remove(UcxList *l, UcxList *e);
1.101 +UcxList *ucx_list_sort(UcxList *list, cmp_func cmpfnc, void *data);
1.102 +
1.103 +UcxList *ucx_list_first(const UcxList *list);
1.104 +UcxList *ucx_list_remove(UcxList *list, UcxList *element);
1.105
1.106 #ifdef __cplusplus
1.107 }
