Mercurial > hg > dav / file diff

--- a/ucx/ucx/avl.h	Mon Feb 04 14:11:57 2019 +0100
+++ b/ucx/ucx/avl.h	Mon Feb 04 17:17:48 2019 +0100
@@ -125,7 +125,7 @@
  * 
  * The cmpfunc should be capable of comparing two keys within this AVL tree.
  * So if you want to use null terminated strings as keys, you could use the
- * ucx_strcmp() function here.
+ * ucx_cmp_str() function here.
  * 
  * @param cmpfunc the compare function that shall be used
  * @param allocator the UcxAllocator that shall be used
@@ -135,17 +135,43 @@
 
 /**
  * Destroys a UcxAVLTree.
+ * 
+ * Note, that the contents are not automatically freed.
+ * Use may use #ucx_avl_free_content() before calling this function.
+ * 
  * @param tree the tree to destroy
+ * @see ucx_avl_free_content()
  */
 void ucx_avl_free(UcxAVLTree *tree);
 
 /**
+ * Frees the contents of a UcxAVLTree.
+ * 
+ * This is a convenience function that iterates over the tree and passes all
+ * values to the specified destructor function.
+ * 
+ * If no destructor is specified (<code>NULL</code>), the free() function of
+ * the tree's own allocator is used.
+ * 
+ * You must ensure, that it is valid to pass each value in the map to the same
+ * destructor function.
+ * 
+ * You should free the entire tree afterwards, as the contents will be invalid.
+ * 
+ * @param tree for which the contents shall be freed
+ * @param destr optional pointer to a destructor function
+ * @see ucx_avl_free()
+ */
+void ucx_avl_free_content(UcxAVLTree *tree, ucx_destructor destr);
+
+/**
  * Macro for initializing a new UcxAVLTree with the default allocator and a
- * ucx_ptrcmp() compare function.
+ * ucx_cmp_ptr() compare function.
  * 
  * @return a new default UcxAVLTree object
  */
-#define ucx_avl_default_new() ucx_avl_new_a(ucx_ptrcmp, ucx_default_allocator())
+#define ucx_avl_default_new() \
+    ucx_avl_new_a(ucx_cmp_ptr, ucx_default_allocator())
 
 /**
  * Gets the node from the tree, that is associated with the specified key.