ucx: comparison ucx/list.h

-:e974640ec4e0
+:aa376dba1ba8
 /**
 * UCX list type.
 * @see UcxList
 */
 typedef struct UcxList UcxList;
 /**
 * UCX list structure.
 */
 struct UcxList {
 /**
 * <code>NULL</code>)
 * @param data additional data for the copy_func()
 * @return a pointer to the copy
 */
 UcxList *ucx_list_clone(UcxList *list, copy_func cpyfnc, void* data);
 /**
 * Creates an element-wise copy of a list using an UcxAllocator.
 *
 * See ucx_list_clone() for details.
 *
 * to ucx_list_first() on the argument must return the argument itself)
 *
 * @param list the list to free
 */
 void ucx_list_free(UcxList *list);
 /**
 * Destroys the entire list using an UcxAllocator.
 *
 * See ucx_list_free() for details.
 *
 * @param allocator the allocator to use
 * @param list the list to free
 * @see ucx_list_free()
 */
 void ucx_list_free_a(UcxAllocator *allocator, UcxList *list);
 /**
 * Inserts an element at the end of the list.
 *
 * This is generally an O(n) operation, as the end of the list is seeked with
 * ucx_list_last().
 * @param data the data to insert
 * @return <code>list</code>, if it is not <code>NULL</code> or a pointer to
 * the newly created list otherwise
 */
 UcxList *ucx_list_append(UcxList *list, void *data);
 /**
 * Inserts an element at the end of the list using an UcxAllocator.
 *
 * See ucx_list_append() for details.
 *
 * @return <code>list</code>, if it is not <code>NULL</code> or a pointer to
 * the newly created list otherwise
 * @see ucx_list_append()
 */
 UcxList *ucx_list_append_a(UcxAllocator *allocator, UcxList *list, void *data);
 /**
 * Inserts an element at the beginning of the list.
 *
 * You <i>should</i> overwrite the old list pointer by calling
 * <code>mylist = ucx_list_prepend(mylist, mydata);</code>. However, you may
 * a new list
 * @param data the data to insert
 * @return a pointer to the new list head
 */
 UcxList *ucx_list_prepend(UcxList *list, void *data);
 /**
 * Inserts an element at the beginning of the list using an UcxAllocator.
 *
 * See ucx_list_prepend() for details.
 *
 * @param data the data to insert
 * @return a pointer to the new list head
 * @see ucx_list_prepend()
 */
 UcxList *ucx_list_prepend_a(UcxAllocator *allocator, UcxList *list, void *data);
 /**
 * Concatenates two lists.
 *
 * Either of the two arguments may be <code>NULL</code>.
 *
 * @param list2 second list
 * @return if <code>list1</code> is <code>NULL</code>, <code>list2</code> is
 * returned, otherwise <code>list1</code> is returned
 */
 UcxList *ucx_list_concat(UcxList *list1, UcxList *list2);
 /**
 * Returns the first element of a list.
 *
 * If the argument is the list pointer, it is directly returned. Otherwise
 * this function traverses to the first element of the list and returns the
 *
 * @param elem one element of the list
 * @return the first element of the list, the specified element is a member of
 */
 UcxList *ucx_list_first(const UcxList *elem);
 /**
 * Returns the last element of a list.
 *
 * If the argument has no successor, it is the last element and therefore
 * directly returned. Otherwise this function traverses to the last element of
 *
 * @param elem one element of the list
 * @return the last element of the list, the specified element is a member of
 */
 UcxList *ucx_list_last(const UcxList *elem);
 /**
 * Returns the list element at the specified index.
 *
 * @param list the list to retrieve the element from
 * @param index index of the element to return
 * @return the element at the specified index or <code>NULL</code>, if the
 * index is greater than the list size
 */
 UcxList *ucx_list_get(const UcxList *list, int index);
 /**
 * Returns the index of an element.
 *
 * @param list the list where to search for the element
 * @param elem the element to find
 * @return the index of the element or -1 if the list does not contain the
 * element
 */
 ssize_t ucx_list_indexof(const UcxList *list, const UcxList *elem);
 /**
 * Returns the element count of the list.
 *
 * @param list the list whose elements are counted
 * @return the element count
 */
 size_t ucx_list_size(const UcxList *list);
 /**
 * Returns the index of an element containing the specified data.
 *
 * This function uses a cmp_func() to compare the data of each list element
 * with the specified data. If no cmp_func is provided, the pointers are
 * @param data additional data for the compare function
 * @return the index of the element containing the specified data or -1 if the
 * data is not found in this list
 */
 ssize_t ucx_list_find(UcxList *list, void *elem, cmp_func cmpfnc, void *data);
 /**
 * Checks, if a list contains a specific element.
 *
 * An element is found, if ucx_list_find() returns a value greater than -1.
 *
 * @param element the element to removed
 * @return returns the updated list pointer or <code>NULL</code>, if the list
 * is now empty
 */
 UcxList *ucx_list_remove(UcxList *list, UcxList *element);
 /**
 * Removes an element from the list using an UcxAllocator.
 *
 * See ucx_list_remove() for details.
 *

Mercurial > hg > ucx / file comparison

comparison: ucx/list.h

ucx/list.h