# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1376054966 -7200
# Node ID b798f2eed26ac3f8196d03c61a7e435b4986d6fa
# Parent  a0aa1c15f46b1359f133f8c9c0b0f2a4a0e00f97
started documentation of map.h + renamed allocator version of ucx_map_new

diff -r a0aa1c15f46b -r b798f2eed26a ucx/map.c
--- a/ucx/map.c	Fri Aug 09 14:36:54 2013 +0200
+++ b/ucx/map.c	Fri Aug 09 15:29:26 2013 +0200
@@ -32,10 +32,10 @@
 #include "map.h"
 
 UcxMap *ucx_map_new(size_t size) {
-    return ucx_map_new_allocator(size, NULL);
+    return ucx_map_new_a(size, NULL);
 }
 
-UcxMap *ucx_map_new_allocator(size_t size, UcxAllocator *allocator) {
+UcxMap *ucx_map_new_a(size_t size, UcxAllocator *allocator) {
     if(size == 0) {
         size = 16;
     }
diff -r a0aa1c15f46b -r b798f2eed26a ucx/map.h
--- a/ucx/map.h	Fri Aug 09 14:36:54 2013 +0200
+++ b/ucx/map.h	Fri Aug 09 15:29:26 2013 +0200
@@ -26,6 +26,18 @@
  * POSSIBILITY OF SUCH DAMAGE.
  */
 
+/**
+ * @file map.h
+ * 
+ * Hash map implementation.
+ * 
+ * This implementation uses murmur hash 2 and separate chaining with linked
+ * lists.
+ * 
+ * @author Mike Becker
+ * @author Olaf Wintermann
+ */
+
 #ifndef UCX_MAP_H
 #define	UCX_MAP_H
 
@@ -46,14 +58,6 @@
 typedef struct UcxMapElement   UcxMapElement;
 typedef struct UcxMapIterator  UcxMapIterator;
 
-/*
- * param 1: element
- * param 2: additional data
- * param 3: size of encoded data will be stored here
- * returns encoded / decoded string or NULL on failure
- */
-typedef void*(*ucx_map_coder)(void*,void*,size_t*);
-
 struct UcxMap {
     UcxAllocator  *allocator;
     UcxMapElement **map;
@@ -79,10 +83,31 @@
     size_t        index;
 };
 
+/**
+ * Creates a new hash map with the specified size.
+ * @param size the size of the hash map
+ * @return a pointer to the new hash map
+ */
+UcxMap *ucx_map_new(size_t size);
 
-UcxMap *ucx_map_new(size_t size);
-UcxMap *ucx_map_new_allocator(size_t size, UcxAllocator *allocator);
+/**
+ * Creates a new hash map with the specified size using an UcxAllocator.
+ * @param size the size of the hash map
+ * @param allocator the allocator to use
+ * @return a pointer to the new hash map
+ */
+UcxMap *ucx_map_new_a(size_t size, UcxAllocator *allocator);
+
+/**
+ * Frees a hash map.
+ * 
+ * <b>Note:</b> the contents are <b>not</b> freed, use an UcxMempool for that
+ * purpose.
+ * 
+ * @param map the map to be freed
+ */
 void ucx_map_free(UcxMap *map);
+
 /* you cannot clone maps with more than 390 mio entries */
 int ucx_map_copy(UcxMap *restrict from, UcxMap *restrict to,
         copy_func fnc, void *data);
@@ -93,26 +118,81 @@
 void* ucx_map_get(UcxMap *map, UcxKey key);
 void* ucx_map_remove(UcxMap *map, UcxKey key);
 
-#define ucx_map_sstr_put(m, s, d) \
-    ucx_map_put(m, ucx_key(s.ptr, s.length), (void*)d)
-#define ucx_map_cstr_put(m, s, d) \
-    ucx_map_put(m, ucx_key((void*)s, strlen(s)), (void*)d)
-#define ucx_map_int_put(m, i, d) \
-    ucx_map_put(m, ucx_key((void*)&i, sizeof(i)), (void*)d)
+/**
+ * Shorthand for putting data with a sstr_t key into the map.
+ * @param map the map
+ * @param key the key
+ * @param value the value
+ * @see ucx_map_put()
+ */
+#define ucx_map_sstr_put(map, key, value) \
+    ucx_map_put(map, ucx_key(key.ptr, key.length), (void*)value)
+/**
+ * Shorthand for putting data with a C string key into the map.
+ * @param map the map
+ * @param key the key
+ * @param value the value
+ * @see ucx_map_put()
+ */
+#define ucx_map_cstr_put(map, key, value) \
+    ucx_map_put(map, ucx_key((void*)key, strlen(key)), (void*)value)
+/**
+ * Shorthand for putting data with an integer key into the map.
+ * @param map the map
+ * @param key the key
+ * @param value the value
+ * @see ucx_map_put()
+ */
+#define ucx_map_int_put(map, key, value) \
+    ucx_map_put(map, ucx_key((void*)&key, sizeof(key)), (void*)value)
 
-#define ucx_map_sstr_get(m, s) \
-    ucx_map_get(m, ucx_key(s.ptr, s.length))
-#define ucx_map_cstr_get(m, s) \
-    ucx_map_get(m, ucx_key((void*)s, strlen(s)))
-#define ucx_map_int_get(m, i) \
-    ucx_map_get(m, ucx_key((void*)&i, sizeof(int)))
 
-#define ucx_map_sstr_remove(m, s) \
-    ucx_map_remove(m, ucx_key(s.ptr, s.length))
-#define ucx_map_cstr_remove(m, s) \
-    ucx_map_remove(m, ucx_key((void*)s, strlen(s)))
-#define ucx_map_int_remove(m, i) \
-    ucx_map_remove(m, ucx_key((void*)&i, sizeof(i)))
+/**
+ * Shorthand for getting data from the map with a sstr_t key.
+ * @param map the map
+ * @param key the key
+ * @see ucx_map_get()
+ */
+#define ucx_map_sstr_get(map, key) \
+    ucx_map_get(map, ucx_key(key.ptr, key.length))
+/**
+ * Shorthand for getting data from the map with a C string key.
+ * @see ucx_map_get()
+ */
+#define ucx_map_cstr_get(map, key) \
+    ucx_map_get(map, ucx_key((void*)key, strlen(key)))
+/**
+ * Shorthand for getting data from the map with an integer key.
+ * @param map the map
+ * @param key the key
+ * @see ucx_map_get()
+ */
+#define ucx_map_int_get(map, key) \
+    ucx_map_get(map, ucx_key((void*)&key, sizeof(int)))
+/**
+ * Shorthand for removing data from the map with a sstr_t key.
+ * @param map the map
+ * @param key the key
+ * @see ucx_map_remove()
+ */
+#define ucx_map_sstr_remove(map, key) \
+    ucx_map_remove(map, ucx_key(key.ptr, key.length))
+/**
+ * Shorthand for removing data from the map with a C string key.
+ * @param map the map
+ * @param key the key
+ * @see ucx_map_remove()
+ */
+#define ucx_map_cstr_remove(map, key) \
+    ucx_map_remove(map, ucx_key((void*)key, strlen(key)))
+/**
+ * Shorthand for removing data from the map with an integer key.
+ * @param map the map
+ * @param key the key
+ * @see ucx_map_remove()
+ */
+#define ucx_map_int_remove(map, key) \
+    ucx_map_remove(map, ucx_key((void*)&key, sizeof(key)))
 
 UcxKey ucx_key(void *data, size_t len);