1.1 --- a/src/cx/map.h Tue Apr 18 18:01:41 2023 +0200
1.2 +++ b/src/cx/map.h Tue Apr 18 19:10:45 2023 +0200
1.3 @@ -102,7 +102,8 @@
1.4 __attribute__((__nonnull__))
1.5 void *(*remove)(
1.6 CxMap *map,
1.7 - CxHashKey key
1.8 + CxHashKey key,
1.9 + bool destroy
1.10 );
1.11
1.12 /**
1.13 @@ -196,7 +197,6 @@
1.14 */
1.15 __attribute__((__nonnull__))
1.16 static inline void cxMapDestroy(CxMap *map) {
1.17 - // TODO: likely to add auto-free feature for contents in the future
1.18 map->cl->destructor(map);
1.19 }
1.20
1.21 @@ -246,42 +246,72 @@
1.22 /**
1.23 * Removes a key/value-pair from the map by using the key.
1.24 *
1.25 - * If this map is storing pointers, you should make sure that the map
1.26 - * is not the last location where this pointer is stored.
1.27 - * Otherwise, use cxMapRemoveAndGet() to retrieve the pointer while
1.28 - * removing it from the map.
1.29 + * Always invokes the destructor function, if any, on the removed element.
1.30 + * If this map is storing pointers and you just want to retrieve the pointer
1.31 + * without invoking the destructor, use cxMapRemoveAndGet().
1.32 + * If you just want to detach the element from the map without invoking the
1.33 + * destructor or returning the element, use cxMapDetach().
1.34 *
1.35 * @param map the map
1.36 * @param key the key
1.37 * @see cxMapRemoveAndGet()
1.38 + * @see cxMapDetach()
1.39 */
1.40 __attribute__((__nonnull__))
1.41 static inline void cxMapRemove(
1.42 CxMap *map,
1.43 CxHashKey key
1.44 ) {
1.45 - (void) map->cl->remove(map, key);
1.46 + (void) map->cl->remove(map, key, true);
1.47 +}
1.48 +
1.49 +/**
1.50 + * Detaches a key/value-pair from the map by using the key
1.51 + * without invoking the destructor.
1.52 + *
1.53 + * In general, you should only use this function if the map does not own
1.54 + * the data and there is a valid reference to the data somewhere else
1.55 + * in the program. In all other cases it is prefarable to use
1.56 + * cxMapRemove() or cxMapRemoveAndGet().
1.57 + *
1.58 + * @param map the map
1.59 + * @param key the key
1.60 + * @see cxMapRemove()
1.61 + * @see cxMapRemoveAndGet()
1.62 + */
1.63 +__attribute__((__nonnull__))
1.64 +static inline void cxMapDetach(
1.65 + CxMap *map,
1.66 + CxHashKey key
1.67 +) {
1.68 + (void) map->cl->remove(map, key, false);
1.69 }
1.70
1.71 /**
1.72 * Removes a key/value-pair from the map by using the key.
1.73 *
1.74 - * This function should only be used when the map is storing pointers,
1.75 - * in order to retrieve the pointer you are about to remove.
1.76 - * In any other case, cxMapRemove() is sufficient.
1.77 + * This function can be used when the map is storing pointers,
1.78 + * in order to retrieve the pointer from the map without invoking
1.79 + * any destructor function. Sometimes you do not want the pointer
1.80 + * to be returned - in that case (instead of suppressing the "unused
1.81 + * result" warning) you can use cxMapDetach().
1.82 + *
1.83 + * If this map is not storing pointers, this function behaves like
1.84 + * cxMapRemove() and returns \c NULL.
1.85 *
1.86 * @param map the map
1.87 * @param key the key
1.88 * @return the stored pointer or \c NULL if either the key is not present
1.89 * in the map or the map is not storing pointers
1.90 * @see cxMapStorePointers()
1.91 + * @see cxMapDetach()
1.92 */
1.93 __attribute__((__nonnull__, __warn_unused_result__))
1.94 static inline void *cxMapRemoveAndGet(
1.95 CxMap *map,
1.96 CxHashKey key
1.97 ) {
1.98 - return map->cl->remove(map, key);
1.99 + return map->cl->remove(map, key, !map->store_pointer);
1.100 }
1.101
1.102 // TODO: set-like map operations (union, intersect, difference)
