diff -r 11f3bb408051 -r 62921b370c60 ucx/list.h
--- a/ucx/list.h Wed Nov 22 12:59:13 2017 +0100
+++ b/ucx/list.h Sun Jan 21 12:13:09 2018 +0100
@@ -1,7 +1,7 @@
/*
* 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:
@@ -46,13 +46,13 @@
/**
* 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 UCX_FOREACH
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 UCX_FOREACH
statement.
- *
* @param list The first element of the list
* @param elem The variable name of the element
*/
@@ -102,13 +102,12 @@
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)
- * argument for the data
parameter, if you want the copy_func() to
- * make use of the allocator.
+ * You might want to pass the allocator via the data
parameter,
+ * to access it within the copy function for making deep copies.
*
* @param allocator the allocator to use
* @param list the list to copy
@@ -146,17 +145,19 @@
* 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.
*
* Caution: the argument MUST 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.
*
@@ -167,6 +168,20 @@
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
@@ -181,7 +196,7 @@
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.
*
@@ -196,6 +211,41 @@
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 NULL
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 list
, if it is not NULL
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 NULL
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 list
, if it is not NULL
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 should overwrite the old list pointer by calling
@@ -212,7 +262,7 @@
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.
*
@@ -327,7 +377,7 @@
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.
@@ -357,7 +407,7 @@
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.
*