comparison: src/cx/map.h
src/cx/map.h
- changeset 686
- 64919f63f059
- parent 685
- 2dd841e364af
- child 689
- 5d0244c6fa3e
equal
deleted
inserted
replaced
| 685:2dd841e364af | 686:64919f63f059 |
|---|---|
| 100 * Removes an element. | 100 * Removes an element. |
| 101 */ | 101 */ |
| 102 __attribute__((__nonnull__)) | 102 __attribute__((__nonnull__)) |
| 103 void *(*remove)( | 103 void *(*remove)( |
| 104 CxMap *map, | 104 CxMap *map, |
| 105 CxHashKey key | 105 CxHashKey key, |
| 106 bool destroy | |
| 106 ); | 107 ); |
| 107 | 108 |
| 108 /** | 109 /** |
| 109 * Iterator over the key/value pairs. | 110 * Iterator over the key/value pairs. |
| 110 */ | 111 */ |
| 194 * | 195 * |
| 195 * @param map the map to be destroyed | 196 * @param map the map to be destroyed |
| 196 */ | 197 */ |
| 197 __attribute__((__nonnull__)) | 198 __attribute__((__nonnull__)) |
| 198 static inline void cxMapDestroy(CxMap *map) { | 199 static inline void cxMapDestroy(CxMap *map) { |
| 199 // TODO: likely to add auto-free feature for contents in the future | |
| 200 map->cl->destructor(map); | 200 map->cl->destructor(map); |
| 201 } | 201 } |
| 202 | 202 |
| 203 | 203 |
| 204 /** | 204 /** |
| 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 /** |
