244 } |
244 } |
245 |
245 |
246 /** |
246 /** |
247 * Removes a key/value-pair from the map by using the key. |
247 * Removes a key/value-pair from the map by using the key. |
248 * |
248 * |
249 * If this map is storing pointers, you should make sure that the map |
249 * Always invokes the destructor function, if any, on the removed element. |
250 * is not the last location where this pointer is stored. |
250 * If this map is storing pointers and you just want to retrieve the pointer |
251 * Otherwise, use cxMapRemoveAndGet() to retrieve the pointer while |
251 * without invoking the destructor, use cxMapRemoveAndGet(). |
252 * removing it from the map. |
252 * If you just want to detach the element from the map without invoking the |
|
253 * destructor or returning the element, use cxMapDetach(). |
253 * |
254 * |
254 * @param map the map |
255 * @param map the map |
255 * @param key the key |
256 * @param key the key |
256 * @see cxMapRemoveAndGet() |
257 * @see cxMapRemoveAndGet() |
|
258 * @see cxMapDetach() |
257 */ |
259 */ |
258 __attribute__((__nonnull__)) |
260 __attribute__((__nonnull__)) |
259 static inline void cxMapRemove( |
261 static inline void cxMapRemove( |
260 CxMap *map, |
262 CxMap *map, |
261 CxHashKey key |
263 CxHashKey key |
262 ) { |
264 ) { |
263 (void) map->cl->remove(map, key); |
265 (void) map->cl->remove(map, key, true); |
|
266 } |
|
267 |
|
268 /** |
|
269 * Detaches a key/value-pair from the map by using the key |
|
270 * without invoking the destructor. |
|
271 * |
|
272 * In general, you should only use this function if the map does not own |
|
273 * the data and there is a valid reference to the data somewhere else |
|
274 * in the program. In all other cases it is prefarable to use |
|
275 * cxMapRemove() or cxMapRemoveAndGet(). |
|
276 * |
|
277 * @param map the map |
|
278 * @param key the key |
|
279 * @see cxMapRemove() |
|
280 * @see cxMapRemoveAndGet() |
|
281 */ |
|
282 __attribute__((__nonnull__)) |
|
283 static inline void cxMapDetach( |
|
284 CxMap *map, |
|
285 CxHashKey key |
|
286 ) { |
|
287 (void) map->cl->remove(map, key, false); |
264 } |
288 } |
265 |
289 |
266 /** |
290 /** |
267 * Removes a key/value-pair from the map by using the key. |
291 * Removes a key/value-pair from the map by using the key. |
268 * |
292 * |
269 * This function should only be used when the map is storing pointers, |
293 * This function can be used when the map is storing pointers, |
270 * in order to retrieve the pointer you are about to remove. |
294 * in order to retrieve the pointer from the map without invoking |
271 * In any other case, cxMapRemove() is sufficient. |
295 * any destructor function. Sometimes you do not want the pointer |
|
296 * to be returned - in that case (instead of suppressing the "unused |
|
297 * result" warning) you can use cxMapDetach(). |
|
298 * |
|
299 * If this map is not storing pointers, this function behaves like |
|
300 * cxMapRemove() and returns \c NULL. |
272 * |
301 * |
273 * @param map the map |
302 * @param map the map |
274 * @param key the key |
303 * @param key the key |
275 * @return the stored pointer or \c NULL if either the key is not present |
304 * @return the stored pointer or \c NULL if either the key is not present |
276 * in the map or the map is not storing pointers |
305 * in the map or the map is not storing pointers |
277 * @see cxMapStorePointers() |
306 * @see cxMapStorePointers() |
|
307 * @see cxMapDetach() |
278 */ |
308 */ |
279 __attribute__((__nonnull__, __warn_unused_result__)) |
309 __attribute__((__nonnull__, __warn_unused_result__)) |
280 static inline void *cxMapRemoveAndGet( |
310 static inline void *cxMapRemoveAndGet( |
281 CxMap *map, |
311 CxMap *map, |
282 CxHashKey key |
312 CxHashKey key |
283 ) { |
313 ) { |
284 return map->cl->remove(map, key); |
314 return map->cl->remove(map, key, !map->store_pointer); |
285 } |
315 } |
286 |
316 |
287 // TODO: set-like map operations (union, intersect, difference) |
317 // TODO: set-like map operations (union, intersect, difference) |
288 |
318 |
289 /** |
319 /** |