Mercurial > hg > toolkit / file diff

--- 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 <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
  */
@@ -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 <code>data</code> parameter, if you want the copy_func() to
- * make use of the allocator.
+ * You might want to pass the allocator via the <code>data</code> 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.
  * 
  * <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.
  * 
@@ -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 <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
@@ -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.
  *