Mercurial > hg > dav / file diff

--- a/ucx/cx/hash_map.h	Thu Nov 28 17:53:13 2024 +0100
+++ b/ucx/cx/hash_map.h	Mon Jan 06 21:18:36 2025 +0100
@@ -26,11 +26,11 @@
  * POSSIBILITY OF SUCH DAMAGE.
  */
 /**
- * \file hash_map.h
- * \brief Hash map implementation.
- * \author Mike Becker
- * \author Olaf Wintermann
- * \copyright 2-Clause BSD License
+ * @file hash_map.h
+ * @brief Hash map implementation.
+ * @author Mike Becker
+ * @author Olaf Wintermann
+ * @copyright 2-Clause BSD License
  */
 
 #ifndef UCX_HASH_MAP_H
@@ -67,23 +67,26 @@
 /**
  * Creates a new hash map with the specified number of buckets.
  *
- * If \p buckets is zero, an implementation defined default will be used.
+ * If @p buckets is zero, an implementation defined default will be used.
  *
- * If \p elem_size is CX_STORE_POINTERS, the created map will be created as if
+ * If @p elem_size is CX_STORE_POINTERS, the created map will be created as if
  * cxMapStorePointers() was called immediately after creation.
  *
  * @note Iterators provided by this hash map implementation provide the remove operation.
  * The index value of an iterator is incremented when the iterator advanced without removal.
- * In other words, when the iterator is finished, \c index==size .
+ * In other words, when the iterator is finished, @c index==size .
  *
  * @param allocator the allocator to use
+ * (if @c NULL, a default stdlib allocator will be used)
  * @param itemsize the size of one element
  * @param buckets the initial number of buckets in this hash map
  * @return a pointer to the new hash map
  */
-__attribute__((__nonnull__, __warn_unused_result__))
+cx_attr_nodiscard
+cx_attr_malloc
+cx_attr_dealloc(cxMapFree, 1)
 CxMap *cxHashMapCreate(
-        CxAllocator const *allocator,
+        const CxAllocator *allocator,
         size_t itemsize,
         size_t buckets
 );
@@ -91,23 +94,22 @@
 /**
  * Creates a new hash map with a default number of buckets.
  *
- * If \p elem_size is CX_STORE_POINTERS, the created map will be created as if
+ * If @p elem_size is CX_STORE_POINTERS, the created map will be created as if
  * cxMapStorePointers() was called immediately after creation.
  *
  * @note Iterators provided by this hash map implementation provide the remove operation.
  * The index value of an iterator is incremented when the iterator advanced without removal.
- * In other words, when the iterator is finished, \c index==size .
+ * In other words, when the iterator is finished, @c index==size .
  *
- * @param itemsize the size of one element
- * @return a pointer to the new hash map
+ * @param itemsize (@c size_t) the size of one element
+ * @return (@c CxMap*) a pointer to the new hash map
  */
-#define cxHashMapCreateSimple(itemsize) \
-    cxHashMapCreate(cxDefaultAllocator, itemsize, 0)
+#define cxHashMapCreateSimple(itemsize) cxHashMapCreate(NULL, itemsize, 0)
 
 /**
  * Increases the number of buckets, if necessary.
  *
- * The load threshold is \c 0.75*buckets. If the element count exceeds the load
+ * The load threshold is @c 0.75*buckets. If the element count exceeds the load
  * threshold, the map will be rehashed. Otherwise, no action is performed and
  * this function simply returns 0.
  *
@@ -120,9 +122,10 @@
  * @note If the specified map is not a hash map, the behavior is undefined.
  *
  * @param map the map to rehash
- * @return zero on success, non-zero if a memory allocation error occurred
+ * @retval zero success
+ * @retval non-zero if a memory allocation error occurred
  */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 int cxMapRehash(CxMap *map);