toolkit: comparison ucx/list.h

-:11f3bb408051
+:62921b370c60
 /*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
-* Copyright 2015 Olaf Wintermann. All rights reserved.
+* Copyright 2016 Olaf Wintermann. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 *   1. Redistributions of source code must retain the above copyright
 #endif
 /**
 * Loop statement for UCX lists.
 *
-* The first argument is a pointer to the list. In most cases this will be the
+* The first argument is the name of the iteration variable. The scope of
+* this variable is limited to the <code>UCX_FOREACH</code> statement.
+*
+* The second argument is a pointer to the list. In most cases this will be the
 * pointer to the first element of the list, but it may also be an arbitrary
 * element of the list. The iteration will then start with that element.
-*
-* The second argument is the name of the iteration variable. The scope of
-* this variable is limited to the <code>UCX_FOREACH</code> statement.
 *
 * @param list The first element of the list
 * @param elem The variable name of the element
 */
 #define UCX_FOREACH(elem,list) \
 * @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.
+* Creates an element-wise copy of a list using a UcxAllocator.
 *
 * See ucx_list_clone() for details.
 *
-* Keep in mind, that you might want to pass the allocator as an (part of the)
+* You might want to pass the allocator via the <code>data</code> parameter,
-* argument for the <code>data</code> parameter, if you want the copy_func() to
+* to access it within the copy function for making deep copies.
-* make use of the allocator.
 *
 * @param allocator the allocator to use
 * @param list the list to copy
 * @param cpyfnc a pointer to the function that shall copy an element (may be
 * <code>NULL</code>)
 /**
 * 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.
+* otherwise referenced or destroyed by ucx_list_free_contents().
+* Otherwise, a memory leak is likely to 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
+* @see ucx_list_free_contents()
 */
 void ucx_list_free(UcxList *list);
 /**
-* Destroys the entire list using an UcxAllocator.
+* Destroys the entire list using a 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);
 /**
+* Destroys the contents of the specified list by calling the specified
+* destructor on each of them.
+*
+* Note, that the contents are not usable afterwards and the list should be
+* destroyed with ucx_list_free().
+*
+* @param list the list for which the contents shall be freed
+* @param destr the destructor function (e.g. stdlib free())
+* @see ucx_list_free()
+*/
+void ucx_list_free_content(UcxList* list, ucx_destructor destr);
+/**
 * Inserts an element at the end of the list.
 *
 * This is generally an O(n) operation, as the end of the list is retrieved with
 * ucx_list_last().
 *
 * 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.
+* Inserts an element at the end of the list using a UcxAllocator.
 *
 * See ucx_list_append() for details.
 *
 * @param allocator the allocator to use
 * @param list the list where to append the data, or <code>NULL</code> to
 * @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 end of the list, if it is not present in the list.
+*
+*
+* @param list the list where to append the data, or <code>NULL</code> to
+* create a new list
+* @param data the data to insert
+* @param cmpfnc the compare function
+* @param cmpdata additional data for the compare function
+* @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_once(UcxList *list, void *data,
+cmp_func cmpfnc, void *cmpdata);
+/**
+* Inserts an element at the end of the list, if it is not present in the list,
+* using a UcxAllocator.
+*
+* See ucx_list_append() for details.
+*
+* @param allocator the allocator to use
+* @param list the list where to append the data, or <code>NULL</code> to
+* create a new list
+* @param data the data to insert
+* @param cmpfnc the compare function
+* @param cmpdata additional data for the compare function
+* @return <code>list</code>, if it is not <code>NULL</code> or a pointer to
+* the newly created list otherwise
+* @see ucx_list_append_a()
+*/
+UcxList *ucx_list_append_once_a(UcxAllocator *allocator,
+UcxList *list, void *data, cmp_func cmpfnc, void *cmpdata);
 /**
 * Inserts an element at the beginning of the list.
 *
 * You <i>should</i> overwrite the old list pointer by calling
 * @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.
+* Inserts an element at the beginning of the list using a UcxAllocator.
 *
 * See ucx_list_prepend() for details.
 *
 * @param allocator the allocator to use
 * @param list the list where to insert the data or <code>NULL</code> to create
 * @see ucx_list_find()
 */
 int ucx_list_contains(UcxList *list, void *elem, cmp_func cmpfnc, void *data);
 /**
-* Sorts an UcxList with natural merge sort.
+* Sorts a UcxList with natural merge sort.
 *
 * This function uses O(n) additional temporary memory for merge operations
 * that is automatically freed after each merge.
 *
 * As the head of the list might change, you <b>MUST</b> call this function
 * is now empty
 */
 UcxList *ucx_list_remove(UcxList *list, UcxList *element);
 /**
-* Removes an element from the list using an UcxAllocator.
+* Removes an element from the list using a UcxAllocator.
 *
 * See ucx_list_remove() for details.
 *
 * @param allocator the allocator to use
 * @param list the list from which the element shall be removed

Mercurial > hg > toolkit / file comparison

comparison: ucx/list.h

ucx/list.h