Mercurial > hg > ucx / changeset

     1.1 --- a/ucx/list.h	Mon Jul 22 13:45:49 2013 +0200
     1.2 +++ b/ucx/list.h	Mon Jul 22 14:51:52 2013 +0200
     1.3 @@ -119,16 +119,48 @@
     1.4  UcxList *ucx_list_append(UcxList *list, void *data);
     1.5  UcxList *ucx_list_prepend(UcxList *list, void *data);
     1.6  UcxList *ucx_list_concat(UcxList *list1, UcxList *list2);
     1.7 -UcxList *ucx_list_last(const UcxList *list);
     1.8 +/**
     1.9 + * Returns the first element of a list.
    1.10 + * 
    1.11 + * If the argument is the list pointer, it is directly returned. Otherwise
    1.12 + * this function traverses to the first element of the list and returns the
    1.13 + * list pointer.
    1.14 + * 
    1.15 + * @param elem one element of the list
    1.16 + * @return the first element of the list, the specified element is a member of
    1.17 + */
    1.18 +UcxList *ucx_list_first(const UcxList *elem);
    1.19 +/**
    1.20 + * Returns the last element of a list.
    1.21 + * 
    1.22 + * If the argument has no successor, it is the last element and therefore
    1.23 + * directly returned. Otherwise this function traverses to the last element of
    1.24 + * the list and returns it.
    1.25 + * 
    1.26 + * @param elem one element of the list
    1.27 + * @return the last element of the list, the specified element is a member of
    1.28 + */
    1.29 +UcxList *ucx_list_last(const UcxList *elem);
    1.30  UcxList *ucx_list_get(const UcxList *list, int index);
    1.31  ssize_t ucx_list_indexof(const UcxList *list, const UcxList *elem);
    1.32  size_t ucx_list_size(const UcxList *list);
    1.33 -ssize_t ucx_list_find(UcxList *list, void *elem, cmp_func fnc, void *cmpdata);
    1.34 -int ucx_list_contains(UcxList *list, void *elem, cmp_func fnc, void *cmpdata);
    1.35 +ssize_t ucx_list_find(UcxList *list, void *elem, cmp_func cmpfnc, void *data);
    1.36 +int ucx_list_contains(UcxList *list, void *elem, cmp_func cmpfnc, void *data);
    1.37  
    1.38  UcxList *ucx_list_sort(UcxList *list, cmp_func cmpfnc, void *data);
    1.39  
    1.40 -UcxList *ucx_list_first(const UcxList *list);
    1.41 +/**
    1.42 + * Removes an element from the list.
    1.43 + * 
    1.44 + * If the first element is removed, the list pointer changes. So it is
    1.45 + * <i>highly recommended</i> to <i>always</i> update the pointer by calling
    1.46 + * <code>mylist = ucx_list_remove(mylist, myelem);</code>.
    1.47 + * 
    1.48 + * @param list the list from which the element shall be removed
    1.49 + * @param element the element to removed
    1.50 + * @return returns the updated list pointer or <code>NULL</code>, if the list
    1.51 + * is now empty
    1.52 + */
    1.53  UcxList *ucx_list_remove(UcxList *list, UcxList *element);
    1.54  
    1.55  #ifdef	__cplusplus