Mercurial > hg > ucx / changeset

     1.1 --- a/ucx/list.c	Tue Jul 23 12:54:45 2013 +0200
     1.2 +++ b/ucx/list.c	Tue Jul 23 14:43:45 2013 +0200
     1.3 @@ -118,13 +118,13 @@
     1.4  }
     1.5  
     1.6  UcxList *ucx_list_concat(UcxList *l1, UcxList *l2) {
     1.7 -    if (l1 == NULL) {
     1.8 -        return l2;
     1.9 -    } else {
    1.10 +    if (l1) {
    1.11          UcxList *last = ucx_list_last(l1);
    1.12          last->next = l2;
    1.13          l2->prev = last;
    1.14          return l1;
    1.15 +    } else {
    1.16 +        return l2;
    1.17      }
    1.18  }
    1.19  
    1.20 @@ -154,7 +154,7 @@
    1.21      if (l == NULL) return NULL;
    1.22  
    1.23      const UcxList *e = l;
    1.24 -    while (e->next != NULL && index > 0) {
    1.25 +    while (e->next && index > 0) {
    1.26          e = e->next;
    1.27          index--;
    1.28      }
    1.29 @@ -165,8 +165,14 @@
    1.30  ssize_t ucx_list_find(UcxList *l, void *elem, cmp_func fnc, void *cmpdata) {
    1.31      ssize_t index = 0;
    1.32      UCX_FOREACH(e, l) {
    1.33 -        if (fnc(elem, e->data, cmpdata) == 0) {
    1.34 -            return index;
    1.35 +        if (fnc) {
    1.36 +            if (fnc(elem, e->data, cmpdata) == 0) {
    1.37 +                return index;
    1.38 +            }
    1.39 +        } else {
    1.40 +            if (elem == e->data) {
    1.41 +                return index;
    1.42 +            }
    1.43          }
    1.44          index++;
    1.45      }

     2.1 --- a/ucx/list.h	Tue Jul 23 12:54:45 2013 +0200
     2.2 +++ b/ucx/list.h	Tue Jul 23 14:43:45 2013 +0200
     2.3 @@ -26,7 +26,7 @@
     2.4   * POSSIBILITY OF SUCH DAMAGE.
     2.5   */
     2.6  /**
     2.7 - * Double linked list implementation.
     2.8 + * Doubly linked list implementation.
     2.9   * 
    2.10   * @file   list.h
    2.11   * @author Mike Becker
    2.12 @@ -81,7 +81,37 @@
    2.13      UcxList *prev;
    2.14  };
    2.15  
    2.16 +/**
    2.17 + * Creates an element-wise copy of a list.
    2.18 + * 
    2.19 + * This function clones the specified list by creating new list elements and
    2.20 + * copying the data with the specified copy_func(). If no copy_func() is
    2.21 + * specified, a shallow copy is created and the new list will reference the
    2.22 + * same data as the source list.
    2.23 + * 
    2.24 + * @param list the list to copy
    2.25 + * @param cpyfnc a pointer to the function that shall copy an element (may be
    2.26 + * <code>NULL</code>)
    2.27 + * @param data additional data for the copy_func()
    2.28 + * @return a pointer to the copy
    2.29 + */
    2.30  UcxList *ucx_list_clone(UcxList *list, copy_func cpyfnc, void* data);
    2.31 +/**
    2.32 + * Creates an element-wise copy of a list using an UcxAllocator.
    2.33 + * 
    2.34 + * See ucx_list_clone() for details.
    2.35 + * 
    2.36 + * Keep in mind, that you might want to pass the allocator as an (part of the)
    2.37 + * argument for the <code>data</code> parameter, if you want the copy_func() to
    2.38 + * make use of the allocator.
    2.39 + * 
    2.40 + * @param list the list to copy
    2.41 + * @param cpyfnc a pointer to the function that shall copy an element (may be
    2.42 + * <code>NULL</code>)
    2.43 + * @param data additional data for the copy_func()
    2.44 + * @return a pointer to the copy
    2.45 + * @see ucx_list_clone()
    2.46 + */
    2.47  UcxList *ucx_list_clone_a(UcxAllocator *allocator, UcxList *list,
    2.48          copy_func cpyfnc, void* data);
    2.49  
    2.50 @@ -115,14 +145,88 @@
    2.51   * <b>Caution:</b> the argument <b>MUST</b> denote an entire list (i.e. a call
    2.52   * to ucx_list_first() on the argument must return the argument itself)
    2.53   * 
    2.54 - * @param list The list to free.
    2.55 + * @param list the list to free
    2.56   */
    2.57  void ucx_list_free(UcxList *list);
    2.58 +/**
    2.59 + * Destroys the entire list using an UcxAllocator.
    2.60 + * 
    2.61 + * See ucx_list_free() for details.
    2.62 + * 
    2.63 + * @param allocator the allocator to use
    2.64 + * @param list the list to free
    2.65 + * @see ucx_list_free()
    2.66 + */
    2.67  void ucx_list_free_a(UcxAllocator *allocator, UcxList *list);
    2.68 +/**
    2.69 + * Inserts an element at the end of the list.
    2.70 + * 
    2.71 + * This is generally an O(n) operation, as the end of the list is seeked with
    2.72 + * ucx_list_last().
    2.73 + * 
    2.74 + * @param list the list where to append the data, or <code>NULL</code> to
    2.75 + * create a new list
    2.76 + * @param data the data to insert
    2.77 + * @return <code>list</code>, if it is not <code>NULL</code> or a pointer to
    2.78 + * the newly created list otherwise
    2.79 + */
    2.80  UcxList *ucx_list_append(UcxList *list, void *data);
    2.81 +/**
    2.82 + * Inserts an element at the end of the list using an UcxAllocator.
    2.83 + * 
    2.84 + * See ucx_list_append() for details.
    2.85 + * 
    2.86 + * @param allocator the allocator to use
    2.87 + * @param list the list where to append the data, or <code>NULL</code> to
    2.88 + * create a new list
    2.89 + * @param data the data to insert
    2.90 + * @return <code>list</code>, if it is not <code>NULL</code> or a pointer to
    2.91 + * the newly created list otherwise
    2.92 + * @see ucx_list_append()
    2.93 + */
    2.94  UcxList *ucx_list_append_a(UcxAllocator *allocator, UcxList *list, void *data);
    2.95 +/**
    2.96 + * Inserts an element at the beginning of the list.
    2.97 + * 
    2.98 + * You <i>should</i> overwrite the old list pointer by calling
    2.99 + * <code>mylist = ucx_list_prepend(mylist, mydata);</code>. However, you may
   2.100 + * also perform successive calls of ucx_list_prepend() on the same list pointer,
   2.101 + * as this function always searchs for the head of the list with
   2.102 + * ucx_list_first().
   2.103 + * 
   2.104 + * @param list the list where to insert the data or <code>NULL</code> to create
   2.105 + * a new list
   2.106 + * @param data the data to insert
   2.107 + * @return a pointer to the new list head
   2.108 + */
   2.109  UcxList *ucx_list_prepend(UcxList *list, void *data);
   2.110 +/**
   2.111 + * Inserts an element at the beginning of the list using an UcxAllocator.
   2.112 + * 
   2.113 + * See ucx_list_prepend() for details.
   2.114 + * 
   2.115 + * @param allocator the allocator to use
   2.116 + * @param list the list where to insert the data or <code>NULL</code> to create
   2.117 + * a new list
   2.118 + * @param data the data to insert
   2.119 + * @return a pointer to the new list head
   2.120 + * @see ucx_list_prepend()
   2.121 + */
   2.122  UcxList *ucx_list_prepend_a(UcxAllocator *allocator, UcxList *list, void *data);
   2.123 +/**
   2.124 + * Concatenates two lists.
   2.125 + * 
   2.126 + * Either of the two arguments may be <code>NULL</code>.
   2.127 + * 
   2.128 + * This function modifies the references to the next/previous element of
   2.129 + * the last/first element of <code>list1</code>/<code>
   2.130 + * list2</code>.
   2.131 + * 
   2.132 + * @param list1 first list
   2.133 + * @param list2 second list
   2.134 + * @return if <code>list1</code> is <code>NULL</code>, <code>list2</code> is
   2.135 + * returned, otherwise <code>list1</code> is returned
   2.136 + */
   2.137  UcxList *ucx_list_concat(UcxList *list1, UcxList *list2);
   2.138  /**
   2.139   * Returns the first element of a list.
   2.140 @@ -146,12 +250,77 @@
   2.141   * @return the last element of the list, the specified element is a member of
   2.142   */
   2.143  UcxList *ucx_list_last(const UcxList *elem);
   2.144 +/**
   2.145 + * Returns the list element at the specified index.
   2.146 + * 
   2.147 + * @param list the list to retrieve the element from
   2.148 + * @param index index of the element to return
   2.149 + * @return the element at the specified index or <code>NULL</code>, if the
   2.150 + * index is greater than the list size
   2.151 + */
   2.152  UcxList *ucx_list_get(const UcxList *list, int index);
   2.153 +/**
   2.154 + * Returns the index of an element.
   2.155 + * 
   2.156 + * @param list the list where to search for the element
   2.157 + * @param elem the element to find
   2.158 + * @return the index of the element or -1 if the list does not contain the
   2.159 + * element
   2.160 + */
   2.161  ssize_t ucx_list_indexof(const UcxList *list, const UcxList *elem);
   2.162 +/**
   2.163 + * Returns the element count of the list.
   2.164 + * 
   2.165 + * @param list the list whose elements are counted
   2.166 + * @return the element count
   2.167 + */
   2.168  size_t ucx_list_size(const UcxList *list);
   2.169 +/**
   2.170 + * Returns the index of an element containing the specified data.
   2.171 + *
   2.172 + * This function uses a cmp_func() to compare the data of each list element
   2.173 + * with the specified data. If no cmp_func is provided, the pointers are
   2.174 + * compared.
   2.175 + * 
   2.176 + * If the list contains the data more than once, the index of the first
   2.177 + * occurrence is returned.
   2.178 + *  
   2.179 + * @param list the list where to search for the data
   2.180 + * @param elem the element data
   2.181 + * @param cmpfnc the compare function
   2.182 + * @param data additional data for the compare function
   2.183 + * @return the index of the element containing the specified data or -1 if the
   2.184 + * data is not found in this list
   2.185 + */
   2.186  ssize_t ucx_list_find(UcxList *list, void *elem, cmp_func cmpfnc, void *data);
   2.187 +/**
   2.188 + * Checks, if a list contains a specific element.
   2.189 + * 
   2.190 + * An element is found, if ucx_list_find() returns a value greater than -1.
   2.191 + * 
   2.192 + * @param list the list where to search for the data
   2.193 + * @param elem the element data
   2.194 + * @param cmpfnc the compare function
   2.195 + * @param data additional data for the compare function
   2.196 + * @return 1, if and only if the list contains the specified element data
   2.197 + * @see ucx_list_find()
   2.198 + */
   2.199  int ucx_list_contains(UcxList *list, void *elem, cmp_func cmpfnc, void *data);
   2.200  
   2.201 +/**
   2.202 + * Sorts an UcxList with natural merge sort.
   2.203 + * 
   2.204 + * This function uses O(n) additional temporary memory for merge operations
   2.205 + * that is automatically freed after each merge.
   2.206 + * 
   2.207 + * As the head of the list might change, you <b>MUST</b> call this function
   2.208 + * as follows: <code>mylist = ucx_list_sort(mylist, mycmpfnc, mydata);</code>.
   2.209 + * 
   2.210 + * @param list the list to sort
   2.211 + * @param cmpfnc the function that shall be used to compare the element data
   2.212 + * @param data additional data for the cmp_func()
   2.213 + * @return the sorted list
   2.214 + */
   2.215  UcxList *ucx_list_sort(UcxList *list, cmp_func cmpfnc, void *data);
   2.216  
   2.217  /**
   2.218 @@ -167,6 +336,17 @@
   2.219   * is now empty
   2.220   */
   2.221  UcxList *ucx_list_remove(UcxList *list, UcxList *element);
   2.222 +/**
   2.223 + * Removes an element from the list using an UcxAllocator.
   2.224 + * 
   2.225 + * See ucx_list_remove() for details.
   2.226 + * 
   2.227 + * @param allocator the allocator to use
   2.228 + * @param list the list from which the element shall be removed
   2.229 + * @param element the element to removed
   2.230 + * @return returns the updated list pointer or <code>NULL</code>, if the list
   2.231 + * @see ucx_list_remove()
   2.232 + */
   2.233  UcxList *ucx_list_remove_a(UcxAllocator *allocator, UcxList *list,
   2.234          UcxList *element);
   2.235  

     3.1 --- a/ucx/test.h	Tue Jul 23 12:54:45 2013 +0200
     3.2 +++ b/ucx/test.h	Tue Jul 23 14:43:45 2013 +0200
     3.3 @@ -47,8 +47,6 @@
     3.4   * PLEASE NOTE: if a test fails, a longjump is performed
     3.5   * back to the UCX_TEST_BEGIN macro!
     3.6   *
     3.7 - * You may use multiple BEGIN-END blocks if you are aware of the
     3.8 - * longjmp behaviour.
     3.9   *
    3.10   */
    3.11