map.h: add return codes to public API

Add all return codes and meanings to the public API

include/cdada/map.h

@@ -58,6 +58,7 @@ typedef void cdada_map_t;
 CDADA_BEGIN_DECLS
 
 //Fwd decl
+//See cdada_map_create() for return codes
 struct __cdada_map_ops;
 cdada_map_t* __cdada_map_create(const uint16_t key_size,
 						struct __cdada_map_ops* ops);
@@ -81,17 +82,30 @@ typedef void (*cdada_map_it)(const cdada_map_t* map, const void* key,
 * TYPE has a size of {1,2,4,8,16,32,64,128,256} bytes
 *
 * For types > 256, use custom containers
+*
+* @returns Returns a cdada_map object or NULL, if some error is found
 */
 #define cdada_map_create(TYPE) \
 	__cdada_map_create(sizeof( TYPE ), NULL)
 
 /**
 * Destroy a map structure
+*
+* @returns Return codes:
+*          CDADA_SUCCESS: map is destroyed
+*          CDADA_E_UNKNOWN: corrupted map or internal error (bug)
+*          CDADA_E_INVALID: map is NULL or corrupted
 */
 int cdada_map_destroy(cdada_map_t* map);
 
 /**
 * Clear the contents of the map
+*
+* @returns Return codes:
+*          CDADA_SUCCESS: map is cleared
+*          CDADA_E_MEM: out of memory
+*          CDADA_E_UNKNOWN: corrupted map or internal error (bug)
+*          CDADA_E_INVALID: map is NULL or corrupted
 */
 int cdada_map_clear(cdada_map_t* map);
 
@@ -101,6 +115,11 @@ int cdada_map_clear(cdada_map_t* map);
 * @param map Map
 * @param func Traverse function for this specific map
 * @param opaque User data (opaque ptr)
+*
+* @returns Return codes:
+*          CDADA_SUCCESS: map was successfully traversed
+*          CDADA_E_UNKNOWN: corrupted map or internal error (bug)
+*          CDADA_E_INVALID: map is NULL or corrupted
 */
 int cdada_map_traverse(const cdada_map_t* map, cdada_map_it func,
 							void* opaque);
@@ -111,6 +130,11 @@ int cdada_map_traverse(const cdada_map_t* map, cdada_map_it func,
 * @param map Map
 * @param func Traverse function for this specific map
 * @param opaque User data (opaque ptr)
+*
+* @returns Return codes:
+*          CDADA_SUCCESS: map was successfully reverse traversed
+*          CDADA_E_UNKNOWN: corrupted map or internal error (bug)
+*          CDADA_E_INVALID: map is NULL or corrupted
 */
 int cdada_map_rtraverse(const cdada_map_t* map, cdada_map_it func,
 							void* opaque);
@@ -119,11 +143,15 @@ int cdada_map_rtraverse(const cdada_map_t* map, cdada_map_it func,
 
 /**
 * Is the map empty
+*
+* @returns Returns true if map is empty else (including invalid) false
 */
 bool cdada_map_empty(const cdada_map_t* map);
 
 /**
 * Return the size (number of elements) in the map
+*
+* @returns Returns number of elements. If map is NULL or corrupted, returns 0
 */
 uint32_t cdada_map_size(const cdada_map_t* map);
 
@@ -135,6 +163,13 @@ uint32_t cdada_map_size(const cdada_map_t* map);
 * @param map Map pointer
 * @param key Key. The key type _must_ have all bytes initialized
 * @param val Pointer to the value
+*
+* @returns Return codes:
+*          CDADA_SUCCESS: element is inserted
+*          CDADA_E_EXISTS: element exists
+*          CDADA_E_MEM: out of memory
+*          CDADA_E_UNKNOWN: corrupted map or internal error (bug)
+*          CDADA_E_INVALID: map is NULL or corrupted
 */
 int cdada_map_insert(cdada_map_t* map, const void* key, void* val);
 
@@ -143,6 +178,13 @@ int cdada_map_insert(cdada_map_t* map, const void* key, void* val);
 *
 * @param map Map pointer
 * @param key Key. The key type _must_ have all bytes initialized
+*
+* @returns Return codes:
+*          CDADA_SUCCESS: element was successfully erased
+*          CDADA_E_NOT_FOUND: no element `key` was found
+*          CDADA_E_MEM: out of memory
+*          CDADA_E_UNKNOWN: corrupted map or internal error (bug)
+*          CDADA_E_INVALID: map is NULL or corrupted
 */
 int cdada_map_erase(cdada_map_t* map, const void* key);
 
@@ -152,6 +194,13 @@ int cdada_map_erase(cdada_map_t* map, const void* key);
 * @param map Map pointer
 * @param key Key to search
 * @param val If element is found, *val will be set to the value pointer
+*
+* @returns Return codes:
+*          CDADA_SUCCESS: element was successfully erased
+*          CDADA_E_NOT_FOUND: no element `key` was found
+*          CDADA_E_MEM: out of memory
+*          CDADA_E_UNKNOWN: corrupted map or internal error (bug)
+*          CDADA_E_INVALID: map is NULL or corrupted or val is NULL
 */
 int cdada_map_find(const cdada_map_t* map, const void* key, void** val);
 
@@ -161,6 +210,12 @@ int cdada_map_find(const cdada_map_t* map, const void* key, void** val);
 * @param key If map has elements, a copy of the first element key will be stored
 *            in *key
 * @param val If map has elements, *val will be set to the value pointer
+*
+* @returns Return codes:
+*          CDADA_SUCCESS: first element was retrieved
+*          CDADA_E_NOT_FOUND: map has no elements
+*          CDADA_E_UNKNOWN: corrupted map or internal error (bug)
+*          CDADA_E_INVALID: map is NULL or corrupted
 */
 int cdada_map_first(const cdada_map_t* map, void* key, void** val);
 
@@ -170,6 +225,12 @@ int cdada_map_first(const cdada_map_t* map, void* key, void** val);
 * @param key If map has elements, a copy of the first element key will be stored
 *            in *key
 * @param val If map has elements, *val will be set to the value pointer
+*
+* @returns Return codes:
+*          CDADA_SUCCESS: last element was retrieved
+*          CDADA_E_NOT_FOUND: map has no elements
+*          CDADA_E_UNKNOWN: corrupted map or internal error (bug)
+*          CDADA_E_INVALID: map is NULL or corrupted
 */
 int cdada_map_last(const cdada_map_t* map, void* key, void** val);
 
@@ -182,6 +243,13 @@ int cdada_map_last(const cdada_map_t* map, void* key, void** val);
 *               'size_used'
 * @param size_used If buffer != NULL, the number of bytes written else number of
 *                  bytes necessary to write, including '\0'
+*
+* @returns Return codes:
+*          CDADA_SUCCESS: map was dumped to buffer
+*          CDADA_E_INCOMPLETE: not enough room in buffer
+*          CDADA_E_MEM: out of memory
+*          CDADA_E_UNKNOWN: corrupted map or internal error (bug)
+*          CDADA_E_INVALID: map is NULL or corrupted
 */
 int cdada_map_dump(cdada_map_t* map, uint32_t size, char* buffer,
 							uint32_t* bytes_used);
@@ -191,6 +259,12 @@ int cdada_map_dump(cdada_map_t* map, uint32_t size, char* buffer,
 *
 * @param map Map object
 * @param stream stdout or stderr
+*
+* @returns Return codes:
+*          CDADA_SUCCESS: map was dumped to `stream`
+*          CDADA_E_MEM: out of memory
+*          CDADA_E_UNKNOWN: corrupted map or internal error (bug)
+*          CDADA_E_INVALID: map is NULL or corrupted
 */
 int cdada_map_print(cdada_map_t* map, FILE *stream);