Mercurial > hg > ucx / file diff

--- a/src/cx/map.h	Tue Apr 18 18:01:41 2023 +0200
+++ b/src/cx/map.h	Tue Apr 18 19:10:45 2023 +0200
@@ -102,7 +102,8 @@
     __attribute__((__nonnull__))
     void *(*remove)(
             CxMap *map,
-            CxHashKey key
+            CxHashKey key,
+            bool destroy
     );
 
     /**
@@ -196,7 +197,6 @@
  */
 __attribute__((__nonnull__))
 static inline void cxMapDestroy(CxMap *map) {
-    // TODO: likely to add auto-free feature for contents in the future
     map->cl->destructor(map);
 }
 
@@ -246,42 +246,72 @@
 /**
  * Removes a key/value-pair from the map by using the key.
  *
- * If this map is storing pointers, you should make sure that the map
- * is not the last location where this pointer is stored.
- * Otherwise, use cxMapRemoveAndGet() to retrieve the pointer while
- * removing it from the map.
+ * Always invokes the destructor function, if any, on the removed element.
+ * If this map is storing pointers and you just want to retrieve the pointer
+ * without invoking the destructor, use cxMapRemoveAndGet().
+ * If you just want to detach the element from the map without invoking the
+ * destructor or returning the element, use cxMapDetach().
  *
  * @param map the map
  * @param key the key
  * @see cxMapRemoveAndGet()
+ * @see cxMapDetach()
  */
 __attribute__((__nonnull__))
 static inline void cxMapRemove(
         CxMap *map,
         CxHashKey key
 ) {
-    (void) map->cl->remove(map, key);
+    (void) map->cl->remove(map, key, true);
+}
+
+/**
+ * Detaches a key/value-pair from the map by using the key
+ * without invoking the destructor.
+ *
+ * In general, you should only use this function if the map does not own
+ * the data and there is a valid reference to the data somewhere else
+ * in the program. In all other cases it is prefarable to use
+ * cxMapRemove() or cxMapRemoveAndGet().
+ *
+ * @param map the map
+ * @param key the key
+ * @see cxMapRemove()
+ * @see cxMapRemoveAndGet()
+ */
+__attribute__((__nonnull__))
+static inline void cxMapDetach(
+        CxMap *map,
+        CxHashKey key
+) {
+    (void) map->cl->remove(map, key, false);
 }
 
 /**
  * Removes a key/value-pair from the map by using the key.
  *
- * This function should only be used when the map is storing pointers,
- * in order to retrieve the pointer you are about to remove.
- * In any other case, cxMapRemove() is sufficient.
+ * This function can be used when the map is storing pointers,
+ * in order to retrieve the pointer from the map without invoking
+ * any destructor function. Sometimes you do not want the pointer
+ * to be returned - in that case (instead of suppressing the "unused
+ * result" warning) you can use cxMapDetach().
+ *
+ * If this map is not storing pointers, this function behaves like
+ * cxMapRemove() and returns \c NULL.
  *
  * @param map the map
  * @param key the key
  * @return the stored pointer or \c NULL if either the key is not present
  * in the map or the map is not storing pointers
  * @see cxMapStorePointers()
+ * @see cxMapDetach()
  */
 __attribute__((__nonnull__, __warn_unused_result__))
 static inline void *cxMapRemoveAndGet(
         CxMap *map,
         CxHashKey key
 ) {
-    return map->cl->remove(map, key);
+    return map->cl->remove(map, key, !map->store_pointer);
 }
 
 // TODO: set-like map operations (union, intersect, difference)