# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1525270480 -7200
# Node ID f819fe5e20f544f8be6c5c8a40cf4ab94650cc93
# Parent  0923c036b9132c50bc77b810e36fb67ddf16d4d0
makes destructor functions for *_free_content() optional + more documentation for UcxProperties

diff -r 0923c036b913 -r f819fe5e20f5 docs/src/modules.md
--- a/docs/src/modules.md	Tue Jan 23 19:23:34 2018 +0100
+++ b/docs/src/modules.md	Wed May 02 16:14:40 2018 +0200
@@ -131,6 +131,38 @@
 This module provides load and store function for `*.properties` files.
 The key/value pairs are stored within an UCX Map.
 
+### Example: Loading properties from a file
+
+```C
+// Open the file as usual
+FILE* file = fopen("myprops.properties", "r");
+if (!file) {
+    // error handling
+    return 1;
+}
+
+// Load the properties from the file
+UcxMap* myprops = ucx_map_new(16);
+if (ucx_properties_load(myprops, file)) {
+    // error handling
+    fclose(file);
+    ucx_map_free(myprops);
+    return 1;
+}
+
+// Print out the key/value pairs
+char* propval;
+UcxMapIterator propiter = ucx_map_iterator(myprops);
+UCX_MAP_FOREACH(key, propval, propiter) {
+    printf("%s = %s\n", (char*)key.data, propval);
+}
+
+// Don't forget to free the values before freeing the map
+ucx_map_free_content(myprops, NULL);
+ucx_map_free(myprops);
+fclose(file);
+```
+
 <a name="stack"></a>
 
 ## Stack
diff -r 0923c036b913 -r f819fe5e20f5 src/list.c
--- a/src/list.c	Tue Jan 23 19:23:34 2018 +0100
+++ b/src/list.c	Wed May 02 16:14:40 2018 +0200
@@ -77,6 +77,7 @@
 }
 
 void ucx_list_free_content(UcxList* list, ucx_destructor destr) {
+    if (!destr) destr = free;
     while (list != NULL) {
         destr(list->data);
         list = list->next;
diff -r 0923c036b913 -r f819fe5e20f5 src/map.c
--- a/src/map.c	Tue Jan 23 19:23:34 2018 +0100
+++ b/src/map.c	Wed May 02 16:14:40 2018 +0200
@@ -86,7 +86,11 @@
     UcxMapIterator iter = ucx_map_iterator(map);
     void *val;
     UCX_MAP_FOREACH(key, val, iter) {
-        destr(val);
+        if (destr) {
+            destr(val);
+        } else {
+            map->allocator->free(val, NULL);
+        }
     }
 }
 
diff -r 0923c036b913 -r f819fe5e20f5 src/ucx/list.h
--- a/src/ucx/list.h	Tue Jan 23 19:23:34 2018 +0100
+++ b/src/ucx/list.h	Wed May 02 16:14:40 2018 +0200
@@ -173,9 +173,11 @@
  * 
  * Note, that the contents are not usable afterwards and the list should be
  * destroyed with ucx_list_free().
+ *
+ * If no destructor is specified (<code>NULL</code>), stdlib's free() is used.
  * 
  * @param list the list for which the contents shall be freed
- * @param destr the destructor function (e.g. stdlib free())
+ * @param destr optional destructor function
  * @see ucx_list_free()
  */
 void ucx_list_free_content(UcxList* list, ucx_destructor destr);
diff -r 0923c036b913 -r f819fe5e20f5 src/ucx/map.h
--- a/src/ucx/map.h	Tue Jan 23 19:23:34 2018 +0100
+++ b/src/ucx/map.h	Wed May 02 16:14:40 2018 +0200
@@ -158,7 +158,10 @@
  * Frees the contents of a hash map.
  * 
  * This is a convenience function that iterates over the map and passes all
- * values to the specified destructor function (e.g. stdlib free()).
+ * values to the specified destructor function.
+ * 
+ * If no destructor is specified (<code>NULL</code>), the free() function of
+ * the map's own allocator is used.
  * 
  * You must ensure, that it is valid to pass each value in the map to the same
  * destructor function.
@@ -166,7 +169,7 @@
  * You should free or clear the map afterwards, as the contents will be invalid.
  * 
  * @param map for which the contents shall be freed
- * @param destr pointer to the destructor function
+ * @param destr optional pointer to a destructor function
  * @see ucx_map_free()
  * @see ucx_map_clear()
  */