Sat, 08 Jun 2024 20:08:09 +0200
add cxIteratorRef() macro
universe@549 | 1 | /* |
universe@549 | 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. |
universe@549 | 3 | * |
universe@549 | 4 | * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved. |
universe@549 | 5 | * |
universe@549 | 6 | * Redistribution and use in source and binary forms, with or without |
universe@549 | 7 | * modification, are permitted provided that the following conditions are met: |
universe@549 | 8 | * |
universe@549 | 9 | * 1. Redistributions of source code must retain the above copyright |
universe@549 | 10 | * notice, this list of conditions and the following disclaimer. |
universe@549 | 11 | * |
universe@549 | 12 | * 2. Redistributions in binary form must reproduce the above copyright |
universe@549 | 13 | * notice, this list of conditions and the following disclaimer in the |
universe@549 | 14 | * documentation and/or other materials provided with the distribution. |
universe@549 | 15 | * |
universe@549 | 16 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" |
universe@549 | 17 | * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
universe@549 | 18 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
universe@549 | 19 | * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE |
universe@549 | 20 | * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
universe@549 | 21 | * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
universe@549 | 22 | * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
universe@549 | 23 | * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
universe@549 | 24 | * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
universe@549 | 25 | * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
universe@549 | 26 | * POSSIBILITY OF SUCH DAMAGE. |
universe@549 | 27 | */ |
universe@549 | 28 | /** |
universe@549 | 29 | * \file map.h |
universe@549 | 30 | * \brief Interface for map implementations. |
universe@549 | 31 | * \author Mike Becker |
universe@549 | 32 | * \author Olaf Wintermann |
universe@549 | 33 | * \copyright 2-Clause BSD License |
universe@549 | 34 | */ |
universe@549 | 35 | |
universe@549 | 36 | #ifndef UCX_MAP_H |
universe@549 | 37 | #define UCX_MAP_H |
universe@549 | 38 | |
universe@681 | 39 | #include "common.h" |
universe@677 | 40 | #include "collection.h" |
universe@691 | 41 | #include "string.h" |
universe@563 | 42 | #include "hash_key.h" |
universe@549 | 43 | |
universe@549 | 44 | #ifdef __cplusplus |
universe@549 | 45 | extern "C" { |
universe@549 | 46 | #endif |
universe@549 | 47 | |
universe@549 | 48 | /** Type for the UCX map. */ |
universe@549 | 49 | typedef struct cx_map_s CxMap; |
universe@549 | 50 | |
universe@549 | 51 | /** Type for a map entry. */ |
universe@549 | 52 | typedef struct cx_map_entry_s CxMapEntry; |
universe@549 | 53 | |
universe@549 | 54 | /** Type for map class definitions. */ |
universe@549 | 55 | typedef struct cx_map_class_s cx_map_class; |
universe@549 | 56 | |
universe@549 | 57 | /** Structure for the UCX map. */ |
universe@549 | 58 | struct cx_map_s { |
universe@854 | 59 | /** |
universe@854 | 60 | * Base attributes. |
universe@854 | 61 | */ |
universe@854 | 62 | CX_COLLECTION_BASE; |
universe@549 | 63 | /** The map class definition. */ |
universe@549 | 64 | cx_map_class *cl; |
universe@549 | 65 | }; |
universe@549 | 66 | |
universe@549 | 67 | /** |
universe@709 | 68 | * The type of iterator for a map. |
universe@709 | 69 | */ |
universe@709 | 70 | enum cx_map_iterator_type { |
universe@709 | 71 | /** |
universe@709 | 72 | * Iterates over key/value pairs. |
universe@709 | 73 | */ |
universe@709 | 74 | CX_MAP_ITERATOR_PAIRS, |
universe@709 | 75 | /** |
universe@709 | 76 | * Iterates over keys only. |
universe@709 | 77 | */ |
universe@709 | 78 | CX_MAP_ITERATOR_KEYS, |
universe@709 | 79 | /** |
universe@709 | 80 | * Iterates over values only. |
universe@709 | 81 | */ |
universe@709 | 82 | CX_MAP_ITERATOR_VALUES |
universe@709 | 83 | }; |
universe@709 | 84 | |
universe@709 | 85 | /** |
universe@549 | 86 | * The class definition for arbitrary maps. |
universe@549 | 87 | */ |
universe@549 | 88 | struct cx_map_class_s { |
universe@549 | 89 | /** |
universe@549 | 90 | * Deallocates the entire memory. |
universe@549 | 91 | */ |
universe@549 | 92 | __attribute__((__nonnull__)) |
universe@549 | 93 | void (*destructor)(struct cx_map_s *map); |
universe@549 | 94 | |
universe@549 | 95 | /** |
universe@549 | 96 | * Removes all elements. |
universe@549 | 97 | */ |
universe@549 | 98 | __attribute__((__nonnull__)) |
universe@549 | 99 | void (*clear)(struct cx_map_s *map); |
universe@549 | 100 | |
universe@549 | 101 | /** |
universe@549 | 102 | * Add or overwrite an element. |
universe@549 | 103 | */ |
universe@549 | 104 | __attribute__((__nonnull__)) |
universe@549 | 105 | int (*put)( |
universe@549 | 106 | CxMap *map, |
universe@563 | 107 | CxHashKey key, |
universe@550 | 108 | void *value |
universe@549 | 109 | ); |
universe@549 | 110 | |
universe@549 | 111 | /** |
universe@549 | 112 | * Returns an element. |
universe@549 | 113 | */ |
universe@549 | 114 | __attribute__((__nonnull__, __warn_unused_result__)) |
universe@549 | 115 | void *(*get)( |
universe@549 | 116 | CxMap const *map, |
universe@563 | 117 | CxHashKey key |
universe@549 | 118 | ); |
universe@549 | 119 | |
universe@549 | 120 | /** |
universe@549 | 121 | * Removes an element. |
universe@549 | 122 | */ |
universe@659 | 123 | __attribute__((__nonnull__)) |
universe@549 | 124 | void *(*remove)( |
universe@550 | 125 | CxMap *map, |
universe@686 | 126 | CxHashKey key, |
universe@686 | 127 | bool destroy |
universe@549 | 128 | ); |
universe@549 | 129 | |
universe@549 | 130 | /** |
universe@709 | 131 | * Creates an iterator for this map. |
universe@549 | 132 | */ |
universe@549 | 133 | __attribute__((__nonnull__, __warn_unused_result__)) |
universe@709 | 134 | CxIterator (*iterator)(CxMap const *map, enum cx_map_iterator_type type); |
universe@549 | 135 | }; |
universe@549 | 136 | |
universe@549 | 137 | /** |
universe@549 | 138 | * A map entry. |
universe@549 | 139 | */ |
universe@549 | 140 | struct cx_map_entry_s { |
universe@549 | 141 | /** |
universe@551 | 142 | * A pointer to the key. |
universe@549 | 143 | */ |
universe@563 | 144 | CxHashKey const *key; |
universe@549 | 145 | /** |
universe@551 | 146 | * A pointer to the value. |
universe@549 | 147 | */ |
universe@551 | 148 | void *value; |
universe@549 | 149 | }; |
universe@549 | 150 | |
universe@714 | 151 | /** |
universe@714 | 152 | * A shared instance of an empty map. |
universe@714 | 153 | * |
universe@714 | 154 | * Writing to that map is undefined. |
universe@714 | 155 | */ |
universe@706 | 156 | extern CxMap *const cxEmptyMap; |
universe@706 | 157 | |
universe@658 | 158 | /** |
universe@658 | 159 | * Advises the map to store copies of the objects (default mode of operation). |
universe@658 | 160 | * |
universe@658 | 161 | * Retrieving objects from this map will yield pointers to the copies stored |
universe@658 | 162 | * within this list. |
universe@658 | 163 | * |
universe@658 | 164 | * @param map the map |
universe@658 | 165 | * @see cxMapStorePointers() |
universe@658 | 166 | */ |
universe@658 | 167 | __attribute__((__nonnull__)) |
universe@658 | 168 | static inline void cxMapStoreObjects(CxMap *map) { |
universe@856 | 169 | map->collection.store_pointer = false; |
universe@658 | 170 | } |
universe@658 | 171 | |
universe@658 | 172 | /** |
universe@658 | 173 | * Advises the map to only store pointers to the objects. |
universe@658 | 174 | * |
universe@658 | 175 | * Retrieving objects from this list will yield the original pointers stored. |
universe@658 | 176 | * |
universe@658 | 177 | * @note This function forcibly sets the element size to the size of a pointer. |
universe@658 | 178 | * Invoking this function on a non-empty map that already stores copies of |
universe@658 | 179 | * objects is undefined. |
universe@658 | 180 | * |
universe@658 | 181 | * @param map the map |
universe@658 | 182 | * @see cxMapStoreObjects() |
universe@658 | 183 | */ |
universe@658 | 184 | __attribute__((__nonnull__)) |
universe@658 | 185 | static inline void cxMapStorePointers(CxMap *map) { |
universe@856 | 186 | map->collection.store_pointer = true; |
universe@856 | 187 | map->collection.elem_size = sizeof(void *); |
universe@658 | 188 | } |
universe@658 | 189 | |
universe@857 | 190 | /** |
universe@857 | 191 | * Returns true, if this map is storing pointers instead of the actual data. |
universe@857 | 192 | * |
universe@857 | 193 | * @param map |
universe@857 | 194 | * @return true, if this map is storing pointers |
universe@857 | 195 | * @see cxMapStorePointers() |
universe@857 | 196 | */ |
universe@857 | 197 | __attribute__((__nonnull__)) |
universe@857 | 198 | static inline bool cxMapIsStoringPointers(CxMap const *map) { |
universe@857 | 199 | return map->collection.store_pointer; |
universe@857 | 200 | } |
universe@549 | 201 | |
universe@549 | 202 | /** |
universe@549 | 203 | * Deallocates the memory of the specified map. |
universe@549 | 204 | * |
universe@549 | 205 | * @param map the map to be destroyed |
universe@549 | 206 | */ |
universe@549 | 207 | __attribute__((__nonnull__)) |
universe@549 | 208 | static inline void cxMapDestroy(CxMap *map) { |
universe@549 | 209 | map->cl->destructor(map); |
universe@549 | 210 | } |
universe@549 | 211 | |
universe@549 | 212 | |
universe@549 | 213 | /** |
universe@549 | 214 | * Clears a map by removing all elements. |
universe@549 | 215 | * |
universe@549 | 216 | * @param map the map to be cleared |
universe@549 | 217 | */ |
universe@549 | 218 | __attribute__((__nonnull__)) |
universe@549 | 219 | static inline void cxMapClear(CxMap *map) { |
universe@549 | 220 | map->cl->clear(map); |
universe@549 | 221 | } |
universe@549 | 222 | |
universe@856 | 223 | /** |
universe@856 | 224 | * Returns the number of elements in this map. |
universe@856 | 225 | * |
universe@856 | 226 | * @param map the map |
universe@856 | 227 | * @return the number of stored elements |
universe@856 | 228 | */ |
universe@856 | 229 | __attribute__((__nonnull__)) |
universe@856 | 230 | static inline size_t cxMapSize(CxMap const *map) { |
universe@856 | 231 | return map->collection.size; |
universe@856 | 232 | } |
universe@856 | 233 | |
universe@549 | 234 | |
universe@549 | 235 | // TODO: set-like map operations (union, intersect, difference) |
universe@549 | 236 | |
universe@549 | 237 | /** |
universe@549 | 238 | * Creates a value iterator for a map. |
universe@549 | 239 | * |
universe@549 | 240 | * \note An iterator iterates over all elements successively. Therefore the order |
universe@549 | 241 | * highly depends on the map implementation and may change arbitrarily when the contents change. |
universe@549 | 242 | * |
universe@549 | 243 | * @param map the map to create the iterator for |
universe@549 | 244 | * @return an iterator for the currently stored values |
universe@549 | 245 | */ |
universe@549 | 246 | __attribute__((__nonnull__, __warn_unused_result__)) |
universe@710 | 247 | static inline CxIterator cxMapIteratorValues(CxMap const *map) { |
universe@709 | 248 | return map->cl->iterator(map, CX_MAP_ITERATOR_VALUES); |
universe@549 | 249 | } |
universe@549 | 250 | |
universe@549 | 251 | /** |
universe@549 | 252 | * Creates a key iterator for a map. |
universe@549 | 253 | * |
universe@564 | 254 | * The elements of the iterator are keys of type CxHashKey. |
universe@555 | 255 | * |
universe@549 | 256 | * \note An iterator iterates over all elements successively. Therefore the order |
universe@549 | 257 | * highly depends on the map implementation and may change arbitrarily when the contents change. |
universe@549 | 258 | * |
universe@549 | 259 | * @param map the map to create the iterator for |
universe@549 | 260 | * @return an iterator for the currently stored keys |
universe@549 | 261 | */ |
universe@549 | 262 | __attribute__((__nonnull__, __warn_unused_result__)) |
universe@710 | 263 | static inline CxIterator cxMapIteratorKeys(CxMap const *map) { |
universe@709 | 264 | return map->cl->iterator(map, CX_MAP_ITERATOR_KEYS); |
universe@549 | 265 | } |
universe@549 | 266 | |
universe@549 | 267 | /** |
universe@549 | 268 | * Creates an iterator for a map. |
universe@549 | 269 | * |
universe@555 | 270 | * The elements of the iterator are key/value pairs of type CxMapEntry. |
universe@549 | 271 | * |
universe@549 | 272 | * \note An iterator iterates over all elements successively. Therefore the order |
universe@549 | 273 | * highly depends on the map implementation and may change arbitrarily when the contents change. |
universe@549 | 274 | * |
universe@549 | 275 | * @param map the map to create the iterator for |
universe@555 | 276 | * @return an iterator for the currently stored entries |
universe@549 | 277 | * @see cxMapIteratorKeys() |
universe@549 | 278 | * @see cxMapIteratorValues() |
universe@549 | 279 | */ |
universe@549 | 280 | __attribute__((__nonnull__, __warn_unused_result__)) |
universe@710 | 281 | static inline CxIterator cxMapIterator(CxMap const *map) { |
universe@709 | 282 | return map->cl->iterator(map, CX_MAP_ITERATOR_PAIRS); |
universe@549 | 283 | } |
universe@549 | 284 | |
universe@630 | 285 | |
universe@630 | 286 | /** |
universe@630 | 287 | * Creates a mutating iterator over the values of a map. |
universe@630 | 288 | * |
universe@630 | 289 | * \note An iterator iterates over all elements successively. Therefore the order |
universe@630 | 290 | * highly depends on the map implementation and may change arbitrarily when the contents change. |
universe@630 | 291 | * |
universe@630 | 292 | * @param map the map to create the iterator for |
universe@630 | 293 | * @return an iterator for the currently stored values |
universe@630 | 294 | */ |
universe@630 | 295 | __attribute__((__nonnull__, __warn_unused_result__)) |
universe@853 | 296 | CxIterator cxMapMutIteratorValues(CxMap *map); |
universe@630 | 297 | |
universe@630 | 298 | /** |
universe@630 | 299 | * Creates a mutating iterator over the keys of a map. |
universe@630 | 300 | * |
universe@630 | 301 | * The elements of the iterator are keys of type CxHashKey. |
universe@630 | 302 | * |
universe@630 | 303 | * \note An iterator iterates over all elements successively. Therefore the order |
universe@630 | 304 | * highly depends on the map implementation and may change arbitrarily when the contents change. |
universe@630 | 305 | * |
universe@630 | 306 | * @param map the map to create the iterator for |
universe@630 | 307 | * @return an iterator for the currently stored keys |
universe@630 | 308 | */ |
universe@630 | 309 | __attribute__((__nonnull__, __warn_unused_result__)) |
universe@853 | 310 | CxIterator cxMapMutIteratorKeys(CxMap *map); |
universe@630 | 311 | |
universe@630 | 312 | /** |
universe@630 | 313 | * Creates a mutating iterator for a map. |
universe@630 | 314 | * |
universe@630 | 315 | * The elements of the iterator are key/value pairs of type CxMapEntry. |
universe@630 | 316 | * |
universe@630 | 317 | * \note An iterator iterates over all elements successively. Therefore the order |
universe@630 | 318 | * highly depends on the map implementation and may change arbitrarily when the contents change. |
universe@630 | 319 | * |
universe@630 | 320 | * @param map the map to create the iterator for |
universe@630 | 321 | * @return an iterator for the currently stored entries |
universe@630 | 322 | * @see cxMapMutIteratorKeys() |
universe@630 | 323 | * @see cxMapMutIteratorValues() |
universe@630 | 324 | */ |
universe@630 | 325 | __attribute__((__nonnull__, __warn_unused_result__)) |
universe@853 | 326 | CxIterator cxMapMutIterator(CxMap *map); |
universe@630 | 327 | |
universe@691 | 328 | #ifdef __cplusplus |
universe@691 | 329 | } // end the extern "C" block here, because we want to start overloading |
universe@691 | 330 | |
universe@691 | 331 | /** |
universe@691 | 332 | * Puts a key/value-pair into the map. |
universe@691 | 333 | * |
universe@691 | 334 | * @param map the map |
universe@691 | 335 | * @param key the key |
universe@691 | 336 | * @param value the value |
universe@691 | 337 | * @return 0 on success, non-zero value on failure |
universe@691 | 338 | */ |
universe@691 | 339 | __attribute__((__nonnull__)) |
universe@691 | 340 | static inline int cxMapPut( |
universe@691 | 341 | CxMap *map, |
universe@691 | 342 | CxHashKey const &key, |
universe@691 | 343 | void *value |
universe@691 | 344 | ) { |
universe@691 | 345 | return map->cl->put(map, key, value); |
universe@549 | 346 | } |
universe@549 | 347 | |
universe@691 | 348 | |
universe@691 | 349 | /** |
universe@691 | 350 | * Puts a key/value-pair into the map. |
universe@691 | 351 | * |
universe@691 | 352 | * @param map the map |
universe@691 | 353 | * @param key the key |
universe@691 | 354 | * @param value the value |
universe@691 | 355 | * @return 0 on success, non-zero value on failure |
universe@691 | 356 | */ |
universe@691 | 357 | __attribute__((__nonnull__)) |
universe@691 | 358 | static inline int cxMapPut( |
universe@691 | 359 | CxMap *map, |
universe@691 | 360 | cxstring const &key, |
universe@691 | 361 | void *value |
universe@691 | 362 | ) { |
universe@691 | 363 | return map->cl->put(map, cx_hash_key_cxstr(key), value); |
universe@691 | 364 | } |
universe@691 | 365 | |
universe@691 | 366 | /** |
universe@691 | 367 | * Puts a key/value-pair into the map. |
universe@691 | 368 | * |
universe@691 | 369 | * @param map the map |
universe@691 | 370 | * @param key the key |
universe@691 | 371 | * @param value the value |
universe@691 | 372 | * @return 0 on success, non-zero value on failure |
universe@691 | 373 | */ |
universe@691 | 374 | __attribute__((__nonnull__)) |
universe@691 | 375 | static inline int cxMapPut( |
universe@691 | 376 | CxMap *map, |
universe@692 | 377 | cxmutstr const &key, |
universe@692 | 378 | void *value |
universe@692 | 379 | ) { |
universe@692 | 380 | return map->cl->put(map, cx_hash_key_cxstr(key), value); |
universe@692 | 381 | } |
universe@692 | 382 | |
universe@692 | 383 | /** |
universe@692 | 384 | * Puts a key/value-pair into the map. |
universe@692 | 385 | * |
universe@692 | 386 | * @param map the map |
universe@692 | 387 | * @param key the key |
universe@692 | 388 | * @param value the value |
universe@692 | 389 | * @return 0 on success, non-zero value on failure |
universe@692 | 390 | */ |
universe@692 | 391 | __attribute__((__nonnull__)) |
universe@692 | 392 | static inline int cxMapPut( |
universe@692 | 393 | CxMap *map, |
universe@691 | 394 | char const *key, |
universe@691 | 395 | void *value |
universe@691 | 396 | ) { |
universe@691 | 397 | return map->cl->put(map, cx_hash_key_str(key), value); |
universe@691 | 398 | } |
universe@691 | 399 | |
universe@691 | 400 | /** |
universe@691 | 401 | * Retrieves a value by using a key. |
universe@691 | 402 | * |
universe@691 | 403 | * @param map the map |
universe@691 | 404 | * @param key the key |
universe@691 | 405 | * @return the value |
universe@691 | 406 | */ |
universe@691 | 407 | __attribute__((__nonnull__, __warn_unused_result__)) |
universe@691 | 408 | static inline void *cxMapGet( |
universe@691 | 409 | CxMap const *map, |
universe@691 | 410 | CxHashKey const &key |
universe@691 | 411 | ) { |
universe@691 | 412 | return map->cl->get(map, key); |
universe@691 | 413 | } |
universe@691 | 414 | |
universe@691 | 415 | /** |
universe@691 | 416 | * Retrieves a value by using a key. |
universe@691 | 417 | * |
universe@691 | 418 | * @param map the map |
universe@691 | 419 | * @param key the key |
universe@691 | 420 | * @return the value |
universe@691 | 421 | */ |
universe@691 | 422 | __attribute__((__nonnull__, __warn_unused_result__)) |
universe@691 | 423 | static inline void *cxMapGet( |
universe@691 | 424 | CxMap const *map, |
universe@691 | 425 | cxstring const &key |
universe@691 | 426 | ) { |
universe@691 | 427 | return map->cl->get(map, cx_hash_key_cxstr(key)); |
universe@691 | 428 | } |
universe@691 | 429 | |
universe@691 | 430 | /** |
universe@691 | 431 | * Retrieves a value by using a key. |
universe@691 | 432 | * |
universe@691 | 433 | * @param map the map |
universe@691 | 434 | * @param key the key |
universe@691 | 435 | * @return the value |
universe@691 | 436 | */ |
universe@691 | 437 | __attribute__((__nonnull__, __warn_unused_result__)) |
universe@691 | 438 | static inline void *cxMapGet( |
universe@691 | 439 | CxMap const *map, |
universe@692 | 440 | cxmutstr const &key |
universe@692 | 441 | ) { |
universe@692 | 442 | return map->cl->get(map, cx_hash_key_cxstr(key)); |
universe@692 | 443 | } |
universe@692 | 444 | |
universe@692 | 445 | /** |
universe@692 | 446 | * Retrieves a value by using a key. |
universe@692 | 447 | * |
universe@692 | 448 | * @param map the map |
universe@692 | 449 | * @param key the key |
universe@692 | 450 | * @return the value |
universe@692 | 451 | */ |
universe@692 | 452 | __attribute__((__nonnull__, __warn_unused_result__)) |
universe@692 | 453 | static inline void *cxMapGet( |
universe@692 | 454 | CxMap const *map, |
universe@691 | 455 | char const *key |
universe@691 | 456 | ) { |
universe@691 | 457 | return map->cl->get(map, cx_hash_key_str(key)); |
universe@691 | 458 | } |
universe@691 | 459 | |
universe@691 | 460 | /** |
universe@691 | 461 | * Removes a key/value-pair from the map by using the key. |
universe@691 | 462 | * |
universe@691 | 463 | * Always invokes the destructor function, if any, on the removed element. |
universe@691 | 464 | * If this map is storing pointers and you just want to retrieve the pointer |
universe@691 | 465 | * without invoking the destructor, use cxMapRemoveAndGet(). |
universe@691 | 466 | * If you just want to detach the element from the map without invoking the |
universe@691 | 467 | * destructor or returning the element, use cxMapDetach(). |
universe@691 | 468 | * |
universe@691 | 469 | * @param map the map |
universe@691 | 470 | * @param key the key |
universe@691 | 471 | * @see cxMapRemoveAndGet() |
universe@691 | 472 | * @see cxMapDetach() |
universe@691 | 473 | */ |
universe@691 | 474 | __attribute__((__nonnull__)) |
universe@691 | 475 | static inline void cxMapRemove( |
universe@691 | 476 | CxMap *map, |
universe@691 | 477 | CxHashKey const &key |
universe@691 | 478 | ) { |
universe@691 | 479 | (void) map->cl->remove(map, key, true); |
universe@691 | 480 | } |
universe@691 | 481 | |
universe@691 | 482 | /** |
universe@691 | 483 | * Removes a key/value-pair from the map by using the key. |
universe@691 | 484 | * |
universe@691 | 485 | * Always invokes the destructor function, if any, on the removed element. |
universe@691 | 486 | * If this map is storing pointers and you just want to retrieve the pointer |
universe@691 | 487 | * without invoking the destructor, use cxMapRemoveAndGet(). |
universe@691 | 488 | * If you just want to detach the element from the map without invoking the |
universe@691 | 489 | * destructor or returning the element, use cxMapDetach(). |
universe@691 | 490 | * |
universe@691 | 491 | * @param map the map |
universe@691 | 492 | * @param key the key |
universe@691 | 493 | * @see cxMapRemoveAndGet() |
universe@691 | 494 | * @see cxMapDetach() |
universe@691 | 495 | */ |
universe@691 | 496 | __attribute__((__nonnull__)) |
universe@691 | 497 | static inline void cxMapRemove( |
universe@691 | 498 | CxMap *map, |
universe@691 | 499 | cxstring const &key |
universe@691 | 500 | ) { |
universe@691 | 501 | (void) map->cl->remove(map, cx_hash_key_cxstr(key), true); |
universe@691 | 502 | } |
universe@691 | 503 | |
universe@691 | 504 | /** |
universe@691 | 505 | * Removes a key/value-pair from the map by using the key. |
universe@691 | 506 | * |
universe@691 | 507 | * Always invokes the destructor function, if any, on the removed element. |
universe@691 | 508 | * If this map is storing pointers and you just want to retrieve the pointer |
universe@691 | 509 | * without invoking the destructor, use cxMapRemoveAndGet(). |
universe@691 | 510 | * If you just want to detach the element from the map without invoking the |
universe@691 | 511 | * destructor or returning the element, use cxMapDetach(). |
universe@691 | 512 | * |
universe@691 | 513 | * @param map the map |
universe@691 | 514 | * @param key the key |
universe@691 | 515 | * @see cxMapRemoveAndGet() |
universe@691 | 516 | * @see cxMapDetach() |
universe@691 | 517 | */ |
universe@691 | 518 | __attribute__((__nonnull__)) |
universe@691 | 519 | static inline void cxMapRemove( |
universe@691 | 520 | CxMap *map, |
universe@692 | 521 | cxmutstr const &key |
universe@692 | 522 | ) { |
universe@692 | 523 | (void) map->cl->remove(map, cx_hash_key_cxstr(key), true); |
universe@692 | 524 | } |
universe@692 | 525 | |
universe@692 | 526 | /** |
universe@692 | 527 | * Removes a key/value-pair from the map by using the key. |
universe@692 | 528 | * |
universe@692 | 529 | * Always invokes the destructor function, if any, on the removed element. |
universe@692 | 530 | * If this map is storing pointers and you just want to retrieve the pointer |
universe@692 | 531 | * without invoking the destructor, use cxMapRemoveAndGet(). |
universe@692 | 532 | * If you just want to detach the element from the map without invoking the |
universe@692 | 533 | * destructor or returning the element, use cxMapDetach(). |
universe@692 | 534 | * |
universe@692 | 535 | * @param map the map |
universe@692 | 536 | * @param key the key |
universe@692 | 537 | * @see cxMapRemoveAndGet() |
universe@692 | 538 | * @see cxMapDetach() |
universe@692 | 539 | */ |
universe@692 | 540 | __attribute__((__nonnull__)) |
universe@692 | 541 | static inline void cxMapRemove( |
universe@692 | 542 | CxMap *map, |
universe@691 | 543 | char const *key |
universe@691 | 544 | ) { |
universe@691 | 545 | (void) map->cl->remove(map, cx_hash_key_str(key), true); |
universe@691 | 546 | } |
universe@691 | 547 | |
universe@691 | 548 | /** |
universe@691 | 549 | * Detaches a key/value-pair from the map by using the key |
universe@691 | 550 | * without invoking the destructor. |
universe@691 | 551 | * |
universe@691 | 552 | * In general, you should only use this function if the map does not own |
universe@691 | 553 | * the data and there is a valid reference to the data somewhere else |
universe@691 | 554 | * in the program. In all other cases it is preferable to use |
universe@691 | 555 | * cxMapRemove() or cxMapRemoveAndGet(). |
universe@691 | 556 | * |
universe@691 | 557 | * @param map the map |
universe@691 | 558 | * @param key the key |
universe@691 | 559 | * @see cxMapRemove() |
universe@691 | 560 | * @see cxMapRemoveAndGet() |
universe@691 | 561 | */ |
universe@691 | 562 | __attribute__((__nonnull__)) |
universe@691 | 563 | static inline void cxMapDetach( |
universe@691 | 564 | CxMap *map, |
universe@691 | 565 | CxHashKey const &key |
universe@691 | 566 | ) { |
universe@691 | 567 | (void) map->cl->remove(map, key, false); |
universe@691 | 568 | } |
universe@691 | 569 | |
universe@691 | 570 | /** |
universe@691 | 571 | * Detaches a key/value-pair from the map by using the key |
universe@691 | 572 | * without invoking the destructor. |
universe@691 | 573 | * |
universe@691 | 574 | * In general, you should only use this function if the map does not own |
universe@691 | 575 | * the data and there is a valid reference to the data somewhere else |
universe@691 | 576 | * in the program. In all other cases it is preferable to use |
universe@691 | 577 | * cxMapRemove() or cxMapRemoveAndGet(). |
universe@691 | 578 | * |
universe@691 | 579 | * @param map the map |
universe@691 | 580 | * @param key the key |
universe@691 | 581 | * @see cxMapRemove() |
universe@691 | 582 | * @see cxMapRemoveAndGet() |
universe@691 | 583 | */ |
universe@691 | 584 | __attribute__((__nonnull__)) |
universe@691 | 585 | static inline void cxMapDetach( |
universe@691 | 586 | CxMap *map, |
universe@691 | 587 | cxstring const &key |
universe@691 | 588 | ) { |
universe@691 | 589 | (void) map->cl->remove(map, cx_hash_key_cxstr(key), false); |
universe@691 | 590 | } |
universe@691 | 591 | |
universe@691 | 592 | /** |
universe@691 | 593 | * Detaches a key/value-pair from the map by using the key |
universe@691 | 594 | * without invoking the destructor. |
universe@691 | 595 | * |
universe@691 | 596 | * In general, you should only use this function if the map does not own |
universe@691 | 597 | * the data and there is a valid reference to the data somewhere else |
universe@691 | 598 | * in the program. In all other cases it is preferable to use |
universe@691 | 599 | * cxMapRemove() or cxMapRemoveAndGet(). |
universe@691 | 600 | * |
universe@691 | 601 | * @param map the map |
universe@691 | 602 | * @param key the key |
universe@691 | 603 | * @see cxMapRemove() |
universe@691 | 604 | * @see cxMapRemoveAndGet() |
universe@691 | 605 | */ |
universe@691 | 606 | __attribute__((__nonnull__)) |
universe@691 | 607 | static inline void cxMapDetach( |
universe@691 | 608 | CxMap *map, |
universe@692 | 609 | cxmutstr const &key |
universe@692 | 610 | ) { |
universe@692 | 611 | (void) map->cl->remove(map, cx_hash_key_cxstr(key), false); |
universe@692 | 612 | } |
universe@692 | 613 | |
universe@692 | 614 | /** |
universe@692 | 615 | * Detaches a key/value-pair from the map by using the key |
universe@692 | 616 | * without invoking the destructor. |
universe@692 | 617 | * |
universe@692 | 618 | * In general, you should only use this function if the map does not own |
universe@692 | 619 | * the data and there is a valid reference to the data somewhere else |
universe@692 | 620 | * in the program. In all other cases it is preferable to use |
universe@692 | 621 | * cxMapRemove() or cxMapRemoveAndGet(). |
universe@692 | 622 | * |
universe@692 | 623 | * @param map the map |
universe@692 | 624 | * @param key the key |
universe@692 | 625 | * @see cxMapRemove() |
universe@692 | 626 | * @see cxMapRemoveAndGet() |
universe@692 | 627 | */ |
universe@692 | 628 | __attribute__((__nonnull__)) |
universe@692 | 629 | static inline void cxMapDetach( |
universe@692 | 630 | CxMap *map, |
universe@691 | 631 | char const *key |
universe@691 | 632 | ) { |
universe@691 | 633 | (void) map->cl->remove(map, cx_hash_key_str(key), false); |
universe@691 | 634 | } |
universe@691 | 635 | |
universe@691 | 636 | /** |
universe@691 | 637 | * Removes a key/value-pair from the map by using the key. |
universe@691 | 638 | * |
universe@691 | 639 | * This function can be used when the map is storing pointers, |
universe@691 | 640 | * in order to retrieve the pointer from the map without invoking |
universe@691 | 641 | * any destructor function. Sometimes you do not want the pointer |
universe@691 | 642 | * to be returned - in that case (instead of suppressing the "unused |
universe@691 | 643 | * result" warning) you can use cxMapDetach(). |
universe@691 | 644 | * |
universe@691 | 645 | * If this map is not storing pointers, this function behaves like |
universe@691 | 646 | * cxMapRemove() and returns \c NULL. |
universe@691 | 647 | * |
universe@691 | 648 | * @param map the map |
universe@691 | 649 | * @param key the key |
universe@691 | 650 | * @return the stored pointer or \c NULL if either the key is not present |
universe@691 | 651 | * in the map or the map is not storing pointers |
universe@691 | 652 | * @see cxMapStorePointers() |
universe@691 | 653 | * @see cxMapDetach() |
universe@691 | 654 | */ |
universe@691 | 655 | __attribute__((__nonnull__, __warn_unused_result__)) |
universe@691 | 656 | static inline void *cxMapRemoveAndGet( |
universe@691 | 657 | CxMap *map, |
universe@691 | 658 | CxHashKey key |
universe@691 | 659 | ) { |
universe@691 | 660 | return map->cl->remove(map, key, !map->store_pointer); |
universe@691 | 661 | } |
universe@691 | 662 | |
universe@691 | 663 | /** |
universe@691 | 664 | * Removes a key/value-pair from the map by using the key. |
universe@691 | 665 | * |
universe@691 | 666 | * This function can be used when the map is storing pointers, |
universe@691 | 667 | * in order to retrieve the pointer from the map without invoking |
universe@691 | 668 | * any destructor function. Sometimes you do not want the pointer |
universe@691 | 669 | * to be returned - in that case (instead of suppressing the "unused |
universe@691 | 670 | * result" warning) you can use cxMapDetach(). |
universe@691 | 671 | * |
universe@691 | 672 | * If this map is not storing pointers, this function behaves like |
universe@691 | 673 | * cxMapRemove() and returns \c NULL. |
universe@691 | 674 | * |
universe@691 | 675 | * @param map the map |
universe@691 | 676 | * @param key the key |
universe@691 | 677 | * @return the stored pointer or \c NULL if either the key is not present |
universe@691 | 678 | * in the map or the map is not storing pointers |
universe@691 | 679 | * @see cxMapStorePointers() |
universe@691 | 680 | * @see cxMapDetach() |
universe@691 | 681 | */ |
universe@691 | 682 | __attribute__((__nonnull__, __warn_unused_result__)) |
universe@691 | 683 | static inline void *cxMapRemoveAndGet( |
universe@691 | 684 | CxMap *map, |
universe@691 | 685 | cxstring key |
universe@691 | 686 | ) { |
universe@691 | 687 | return map->cl->remove(map, cx_hash_key_cxstr(key), !map->store_pointer); |
universe@691 | 688 | } |
universe@691 | 689 | |
universe@691 | 690 | /** |
universe@691 | 691 | * Removes a key/value-pair from the map by using the key. |
universe@691 | 692 | * |
universe@691 | 693 | * This function can be used when the map is storing pointers, |
universe@691 | 694 | * in order to retrieve the pointer from the map without invoking |
universe@691 | 695 | * any destructor function. Sometimes you do not want the pointer |
universe@691 | 696 | * to be returned - in that case (instead of suppressing the "unused |
universe@691 | 697 | * result" warning) you can use cxMapDetach(). |
universe@691 | 698 | * |
universe@691 | 699 | * If this map is not storing pointers, this function behaves like |
universe@691 | 700 | * cxMapRemove() and returns \c NULL. |
universe@691 | 701 | * |
universe@691 | 702 | * @param map the map |
universe@691 | 703 | * @param key the key |
universe@691 | 704 | * @return the stored pointer or \c NULL if either the key is not present |
universe@691 | 705 | * in the map or the map is not storing pointers |
universe@691 | 706 | * @see cxMapStorePointers() |
universe@691 | 707 | * @see cxMapDetach() |
universe@691 | 708 | */ |
universe@691 | 709 | __attribute__((__nonnull__, __warn_unused_result__)) |
universe@691 | 710 | static inline void *cxMapRemoveAndGet( |
universe@691 | 711 | CxMap *map, |
universe@692 | 712 | cxmutstr key |
universe@692 | 713 | ) { |
universe@692 | 714 | return map->cl->remove(map, cx_hash_key_cxstr(key), !map->store_pointer); |
universe@692 | 715 | } |
universe@692 | 716 | |
universe@692 | 717 | /** |
universe@692 | 718 | * Removes a key/value-pair from the map by using the key. |
universe@692 | 719 | * |
universe@692 | 720 | * This function can be used when the map is storing pointers, |
universe@692 | 721 | * in order to retrieve the pointer from the map without invoking |
universe@692 | 722 | * any destructor function. Sometimes you do not want the pointer |
universe@692 | 723 | * to be returned - in that case (instead of suppressing the "unused |
universe@692 | 724 | * result" warning) you can use cxMapDetach(). |
universe@692 | 725 | * |
universe@692 | 726 | * If this map is not storing pointers, this function behaves like |
universe@692 | 727 | * cxMapRemove() and returns \c NULL. |
universe@692 | 728 | * |
universe@692 | 729 | * @param map the map |
universe@692 | 730 | * @param key the key |
universe@692 | 731 | * @return the stored pointer or \c NULL if either the key is not present |
universe@692 | 732 | * in the map or the map is not storing pointers |
universe@692 | 733 | * @see cxMapStorePointers() |
universe@692 | 734 | * @see cxMapDetach() |
universe@692 | 735 | */ |
universe@692 | 736 | __attribute__((__nonnull__, __warn_unused_result__)) |
universe@692 | 737 | static inline void *cxMapRemoveAndGet( |
universe@692 | 738 | CxMap *map, |
universe@691 | 739 | char const *key |
universe@691 | 740 | ) { |
universe@691 | 741 | return map->cl->remove(map, cx_hash_key_str(key), !map->store_pointer); |
universe@691 | 742 | } |
universe@691 | 743 | |
universe@691 | 744 | #else // __cplusplus |
universe@691 | 745 | |
universe@691 | 746 | /** |
universe@691 | 747 | * Puts a key/value-pair into the map. |
universe@691 | 748 | * |
universe@691 | 749 | * @param map the map |
universe@691 | 750 | * @param key the key |
universe@691 | 751 | * @param value the value |
universe@691 | 752 | * @return 0 on success, non-zero value on failure |
universe@691 | 753 | */ |
universe@691 | 754 | __attribute__((__nonnull__)) |
universe@691 | 755 | static inline int cx_map_put( |
universe@691 | 756 | CxMap *map, |
universe@691 | 757 | CxHashKey key, |
universe@691 | 758 | void *value |
universe@691 | 759 | ) { |
universe@691 | 760 | return map->cl->put(map, key, value); |
universe@691 | 761 | } |
universe@691 | 762 | |
universe@691 | 763 | /** |
universe@691 | 764 | * Puts a key/value-pair into the map. |
universe@691 | 765 | * |
universe@691 | 766 | * @param map the map |
universe@691 | 767 | * @param key the key |
universe@691 | 768 | * @param value the value |
universe@691 | 769 | * @return 0 on success, non-zero value on failure |
universe@691 | 770 | */ |
universe@691 | 771 | __attribute__((__nonnull__)) |
universe@691 | 772 | static inline int cx_map_put_cxstr( |
universe@691 | 773 | CxMap *map, |
universe@691 | 774 | cxstring key, |
universe@691 | 775 | void *value |
universe@691 | 776 | ) { |
universe@691 | 777 | return map->cl->put(map, cx_hash_key_cxstr(key), value); |
universe@691 | 778 | } |
universe@691 | 779 | |
universe@691 | 780 | /** |
universe@691 | 781 | * Puts a key/value-pair into the map. |
universe@691 | 782 | * |
universe@691 | 783 | * @param map the map |
universe@691 | 784 | * @param key the key |
universe@691 | 785 | * @param value the value |
universe@691 | 786 | * @return 0 on success, non-zero value on failure |
universe@691 | 787 | */ |
universe@691 | 788 | __attribute__((__nonnull__)) |
universe@692 | 789 | static inline int cx_map_put_mustr( |
universe@692 | 790 | CxMap *map, |
universe@692 | 791 | cxmutstr key, |
universe@692 | 792 | void *value |
universe@692 | 793 | ) { |
universe@692 | 794 | return map->cl->put(map, cx_hash_key_cxstr(key), value); |
universe@692 | 795 | } |
universe@692 | 796 | |
universe@692 | 797 | /** |
universe@692 | 798 | * Puts a key/value-pair into the map. |
universe@692 | 799 | * |
universe@692 | 800 | * @param map the map |
universe@692 | 801 | * @param key the key |
universe@692 | 802 | * @param value the value |
universe@692 | 803 | * @return 0 on success, non-zero value on failure |
universe@692 | 804 | */ |
universe@692 | 805 | __attribute__((__nonnull__)) |
universe@691 | 806 | static inline int cx_map_put_str( |
universe@691 | 807 | CxMap *map, |
universe@691 | 808 | char const *key, |
universe@691 | 809 | void *value |
universe@691 | 810 | ) { |
universe@691 | 811 | return map->cl->put(map, cx_hash_key_str(key), value); |
universe@691 | 812 | } |
universe@691 | 813 | |
universe@691 | 814 | /** |
universe@691 | 815 | * Puts a key/value-pair into the map. |
universe@691 | 816 | * |
universe@691 | 817 | * @param map the map |
universe@691 | 818 | * @param key the key |
universe@691 | 819 | * @param value the value |
universe@691 | 820 | * @return 0 on success, non-zero value on failure |
universe@691 | 821 | */ |
universe@691 | 822 | #define cxMapPut(map, key, value) _Generic((key), \ |
universe@691 | 823 | CxHashKey: cx_map_put, \ |
universe@691 | 824 | cxstring: cx_map_put_cxstr, \ |
universe@692 | 825 | cxmutstr: cx_map_put_mustr, \ |
universe@694 | 826 | char*: cx_map_put_str, \ |
universe@694 | 827 | char const*: cx_map_put_str) \ |
universe@691 | 828 | (map, key, value) |
universe@691 | 829 | |
universe@691 | 830 | /** |
universe@691 | 831 | * Retrieves a value by using a key. |
universe@691 | 832 | * |
universe@691 | 833 | * @param map the map |
universe@691 | 834 | * @param key the key |
universe@691 | 835 | * @return the value |
universe@691 | 836 | */ |
universe@691 | 837 | __attribute__((__nonnull__, __warn_unused_result__)) |
universe@691 | 838 | static inline void *cx_map_get( |
universe@691 | 839 | CxMap const *map, |
universe@691 | 840 | CxHashKey key |
universe@691 | 841 | ) { |
universe@691 | 842 | return map->cl->get(map, key); |
universe@691 | 843 | } |
universe@691 | 844 | |
universe@691 | 845 | /** |
universe@691 | 846 | * Retrieves a value by using a key. |
universe@691 | 847 | * |
universe@691 | 848 | * @param map the map |
universe@691 | 849 | * @param key the key |
universe@691 | 850 | * @return the value |
universe@691 | 851 | */ |
universe@691 | 852 | __attribute__((__nonnull__, __warn_unused_result__)) |
universe@691 | 853 | static inline void *cx_map_get_cxstr( |
universe@691 | 854 | CxMap const *map, |
universe@691 | 855 | cxstring key |
universe@691 | 856 | ) { |
universe@691 | 857 | return map->cl->get(map, cx_hash_key_cxstr(key)); |
universe@691 | 858 | } |
universe@691 | 859 | |
universe@691 | 860 | /** |
universe@691 | 861 | * Retrieves a value by using a key. |
universe@691 | 862 | * |
universe@691 | 863 | * @param map the map |
universe@691 | 864 | * @param key the key |
universe@691 | 865 | * @return the value |
universe@691 | 866 | */ |
universe@691 | 867 | __attribute__((__nonnull__, __warn_unused_result__)) |
universe@692 | 868 | static inline void *cx_map_get_mustr( |
universe@692 | 869 | CxMap const *map, |
universe@692 | 870 | cxmutstr key |
universe@692 | 871 | ) { |
universe@692 | 872 | return map->cl->get(map, cx_hash_key_cxstr(key)); |
universe@692 | 873 | } |
universe@692 | 874 | |
universe@692 | 875 | /** |
universe@692 | 876 | * Retrieves a value by using a key. |
universe@692 | 877 | * |
universe@692 | 878 | * @param map the map |
universe@692 | 879 | * @param key the key |
universe@692 | 880 | * @return the value |
universe@692 | 881 | */ |
universe@692 | 882 | __attribute__((__nonnull__, __warn_unused_result__)) |
universe@691 | 883 | static inline void *cx_map_get_str( |
universe@691 | 884 | CxMap const *map, |
universe@691 | 885 | char const *key |
universe@691 | 886 | ) { |
universe@691 | 887 | return map->cl->get(map, cx_hash_key_str(key)); |
universe@691 | 888 | } |
universe@691 | 889 | |
universe@691 | 890 | /** |
universe@691 | 891 | * Retrieves a value by using a key. |
universe@691 | 892 | * |
universe@691 | 893 | * @param map the map |
universe@691 | 894 | * @param key the key |
universe@691 | 895 | * @return the value |
universe@691 | 896 | */ |
universe@691 | 897 | #define cxMapGet(map, key) _Generic((key), \ |
universe@691 | 898 | CxHashKey: cx_map_get, \ |
universe@691 | 899 | cxstring: cx_map_get_cxstr, \ |
universe@692 | 900 | cxmutstr: cx_map_get_mustr, \ |
universe@694 | 901 | char*: cx_map_get_str, \ |
universe@694 | 902 | char const*: cx_map_get_str) \ |
universe@691 | 903 | (map, key) |
universe@691 | 904 | |
universe@691 | 905 | /** |
universe@691 | 906 | * Removes a key/value-pair from the map by using the key. |
universe@691 | 907 | * |
universe@691 | 908 | * @param map the map |
universe@691 | 909 | * @param key the key |
universe@691 | 910 | */ |
universe@691 | 911 | __attribute__((__nonnull__)) |
universe@691 | 912 | static inline void cx_map_remove( |
universe@691 | 913 | CxMap *map, |
universe@691 | 914 | CxHashKey key |
universe@691 | 915 | ) { |
universe@691 | 916 | (void) map->cl->remove(map, key, true); |
universe@691 | 917 | } |
universe@691 | 918 | |
universe@691 | 919 | /** |
universe@691 | 920 | * Removes a key/value-pair from the map by using the key. |
universe@691 | 921 | * |
universe@691 | 922 | * @param map the map |
universe@691 | 923 | * @param key the key |
universe@691 | 924 | */ |
universe@691 | 925 | __attribute__((__nonnull__)) |
universe@691 | 926 | static inline void cx_map_remove_cxstr( |
universe@691 | 927 | CxMap *map, |
universe@691 | 928 | cxstring key |
universe@691 | 929 | ) { |
universe@691 | 930 | (void) map->cl->remove(map, cx_hash_key_cxstr(key), true); |
universe@691 | 931 | } |
universe@691 | 932 | |
universe@691 | 933 | /** |
universe@691 | 934 | * Removes a key/value-pair from the map by using the key. |
universe@691 | 935 | * |
universe@691 | 936 | * @param map the map |
universe@691 | 937 | * @param key the key |
universe@691 | 938 | */ |
universe@691 | 939 | __attribute__((__nonnull__)) |
universe@692 | 940 | static inline void cx_map_remove_mustr( |
universe@692 | 941 | CxMap *map, |
universe@692 | 942 | cxmutstr key |
universe@692 | 943 | ) { |
universe@692 | 944 | (void) map->cl->remove(map, cx_hash_key_cxstr(key), true); |
universe@692 | 945 | } |
universe@692 | 946 | |
universe@692 | 947 | /** |
universe@692 | 948 | * Removes a key/value-pair from the map by using the key. |
universe@692 | 949 | * |
universe@692 | 950 | * @param map the map |
universe@692 | 951 | * @param key the key |
universe@692 | 952 | */ |
universe@692 | 953 | __attribute__((__nonnull__)) |
universe@691 | 954 | static inline void cx_map_remove_str( |
universe@691 | 955 | CxMap *map, |
universe@691 | 956 | char const *key |
universe@691 | 957 | ) { |
universe@691 | 958 | (void) map->cl->remove(map, cx_hash_key_str(key), true); |
universe@691 | 959 | } |
universe@691 | 960 | |
universe@691 | 961 | /** |
universe@691 | 962 | * Removes a key/value-pair from the map by using the key. |
universe@691 | 963 | * |
universe@691 | 964 | * Always invokes the destructor function, if any, on the removed element. |
universe@691 | 965 | * If this map is storing pointers and you just want to retrieve the pointer |
universe@691 | 966 | * without invoking the destructor, use cxMapRemoveAndGet(). |
universe@691 | 967 | * If you just want to detach the element from the map without invoking the |
universe@691 | 968 | * destructor or returning the element, use cxMapDetach(). |
universe@691 | 969 | * |
universe@691 | 970 | * @param map the map |
universe@691 | 971 | * @param key the key |
universe@691 | 972 | * @see cxMapRemoveAndGet() |
universe@691 | 973 | * @see cxMapDetach() |
universe@691 | 974 | */ |
universe@691 | 975 | #define cxMapRemove(map, key) _Generic((key), \ |
universe@691 | 976 | CxHashKey: cx_map_remove, \ |
universe@691 | 977 | cxstring: cx_map_remove_cxstr, \ |
universe@692 | 978 | cxmutstr: cx_map_remove_mustr, \ |
universe@694 | 979 | char*: cx_map_remove_str, \ |
universe@694 | 980 | char const*: cx_map_remove_str) \ |
universe@691 | 981 | (map, key) |
universe@691 | 982 | |
universe@691 | 983 | /** |
universe@691 | 984 | * Detaches a key/value-pair from the map by using the key |
universe@691 | 985 | * without invoking the destructor. |
universe@691 | 986 | * |
universe@691 | 987 | * @param map the map |
universe@691 | 988 | * @param key the key |
universe@691 | 989 | */ |
universe@691 | 990 | __attribute__((__nonnull__)) |
universe@691 | 991 | static inline void cx_map_detach( |
universe@691 | 992 | CxMap *map, |
universe@691 | 993 | CxHashKey key |
universe@691 | 994 | ) { |
universe@691 | 995 | (void) map->cl->remove(map, key, false); |
universe@691 | 996 | } |
universe@691 | 997 | |
universe@691 | 998 | /** |
universe@691 | 999 | * Detaches a key/value-pair from the map by using the key |
universe@691 | 1000 | * without invoking the destructor. |
universe@691 | 1001 | * |
universe@691 | 1002 | * @param map the map |
universe@691 | 1003 | * @param key the key |
universe@691 | 1004 | */ |
universe@691 | 1005 | __attribute__((__nonnull__)) |
universe@691 | 1006 | static inline void cx_map_detach_cxstr( |
universe@691 | 1007 | CxMap *map, |
universe@691 | 1008 | cxstring key |
universe@691 | 1009 | ) { |
universe@691 | 1010 | (void) map->cl->remove(map, cx_hash_key_cxstr(key), false); |
universe@691 | 1011 | } |
universe@691 | 1012 | |
universe@691 | 1013 | /** |
universe@691 | 1014 | * Detaches a key/value-pair from the map by using the key |
universe@691 | 1015 | * without invoking the destructor. |
universe@691 | 1016 | * |
universe@691 | 1017 | * @param map the map |
universe@691 | 1018 | * @param key the key |
universe@691 | 1019 | */ |
universe@691 | 1020 | __attribute__((__nonnull__)) |
universe@692 | 1021 | static inline void cx_map_detach_mustr( |
universe@692 | 1022 | CxMap *map, |
universe@692 | 1023 | cxmutstr key |
universe@692 | 1024 | ) { |
universe@692 | 1025 | (void) map->cl->remove(map, cx_hash_key_cxstr(key), false); |
universe@692 | 1026 | } |
universe@692 | 1027 | |
universe@692 | 1028 | /** |
universe@692 | 1029 | * Detaches a key/value-pair from the map by using the key |
universe@692 | 1030 | * without invoking the destructor. |
universe@692 | 1031 | * |
universe@692 | 1032 | * @param map the map |
universe@692 | 1033 | * @param key the key |
universe@692 | 1034 | */ |
universe@692 | 1035 | __attribute__((__nonnull__)) |
universe@691 | 1036 | static inline void cx_map_detach_str( |
universe@691 | 1037 | CxMap *map, |
universe@691 | 1038 | char const *key |
universe@691 | 1039 | ) { |
universe@691 | 1040 | (void) map->cl->remove(map, cx_hash_key_str(key), false); |
universe@691 | 1041 | } |
universe@691 | 1042 | |
universe@691 | 1043 | /** |
universe@691 | 1044 | * Detaches a key/value-pair from the map by using the key |
universe@691 | 1045 | * without invoking the destructor. |
universe@691 | 1046 | * |
universe@691 | 1047 | * In general, you should only use this function if the map does not own |
universe@691 | 1048 | * the data and there is a valid reference to the data somewhere else |
universe@691 | 1049 | * in the program. In all other cases it is preferable to use |
universe@691 | 1050 | * cxMapRemove() or cxMapRemoveAndGet(). |
universe@691 | 1051 | * |
universe@691 | 1052 | * @param map the map |
universe@691 | 1053 | * @param key the key |
universe@691 | 1054 | * @see cxMapRemove() |
universe@691 | 1055 | * @see cxMapRemoveAndGet() |
universe@691 | 1056 | */ |
universe@691 | 1057 | #define cxMapDetach(map, key) _Generic((key), \ |
universe@691 | 1058 | CxHashKey: cx_map_detach, \ |
universe@691 | 1059 | cxstring: cx_map_detach_cxstr, \ |
universe@692 | 1060 | cxmutstr: cx_map_detach_mustr, \ |
universe@694 | 1061 | char*: cx_map_detach_str, \ |
universe@694 | 1062 | char const*: cx_map_detach_str) \ |
universe@691 | 1063 | (map, key) |
universe@691 | 1064 | |
universe@691 | 1065 | /** |
universe@691 | 1066 | * Removes a key/value-pair from the map by using the key. |
universe@691 | 1067 | * |
universe@691 | 1068 | * @param map the map |
universe@691 | 1069 | * @param key the key |
universe@691 | 1070 | * @return the stored pointer or \c NULL if either the key is not present |
universe@691 | 1071 | * in the map or the map is not storing pointers |
universe@691 | 1072 | */ |
universe@691 | 1073 | __attribute__((__nonnull__, __warn_unused_result__)) |
universe@691 | 1074 | static inline void *cx_map_remove_and_get( |
universe@691 | 1075 | CxMap *map, |
universe@691 | 1076 | CxHashKey key |
universe@691 | 1077 | ) { |
universe@856 | 1078 | return map->cl->remove(map, key, !map->collection.store_pointer); |
universe@691 | 1079 | } |
universe@691 | 1080 | |
universe@691 | 1081 | /** |
universe@691 | 1082 | * Removes a key/value-pair from the map by using the key. |
universe@691 | 1083 | * |
universe@691 | 1084 | * @param map the map |
universe@691 | 1085 | * @param key the key |
universe@691 | 1086 | * @return the stored pointer or \c NULL if either the key is not present |
universe@691 | 1087 | * in the map or the map is not storing pointers |
universe@691 | 1088 | */ |
universe@691 | 1089 | __attribute__((__nonnull__, __warn_unused_result__)) |
universe@691 | 1090 | static inline void *cx_map_remove_and_get_cxstr( |
universe@691 | 1091 | CxMap *map, |
universe@691 | 1092 | cxstring key |
universe@691 | 1093 | ) { |
universe@856 | 1094 | return map->cl->remove(map, cx_hash_key_cxstr(key), !map->collection.store_pointer); |
universe@691 | 1095 | } |
universe@691 | 1096 | |
universe@691 | 1097 | /** |
universe@691 | 1098 | * Removes a key/value-pair from the map by using the key. |
universe@691 | 1099 | * |
universe@691 | 1100 | * @param map the map |
universe@691 | 1101 | * @param key the key |
universe@691 | 1102 | * @return the stored pointer or \c NULL if either the key is not present |
universe@691 | 1103 | * in the map or the map is not storing pointers |
universe@691 | 1104 | */ |
universe@691 | 1105 | __attribute__((__nonnull__, __warn_unused_result__)) |
universe@692 | 1106 | static inline void *cx_map_remove_and_get_mustr( |
universe@692 | 1107 | CxMap *map, |
universe@692 | 1108 | cxmutstr key |
universe@692 | 1109 | ) { |
universe@856 | 1110 | return map->cl->remove(map, cx_hash_key_cxstr(key), !map->collection.store_pointer); |
universe@692 | 1111 | } |
universe@692 | 1112 | |
universe@692 | 1113 | /** |
universe@692 | 1114 | * Removes a key/value-pair from the map by using the key. |
universe@692 | 1115 | * |
universe@692 | 1116 | * @param map the map |
universe@692 | 1117 | * @param key the key |
universe@692 | 1118 | * @return the stored pointer or \c NULL if either the key is not present |
universe@692 | 1119 | * in the map or the map is not storing pointers |
universe@692 | 1120 | */ |
universe@692 | 1121 | __attribute__((__nonnull__, __warn_unused_result__)) |
universe@691 | 1122 | static inline void *cx_map_remove_and_get_str( |
universe@691 | 1123 | CxMap *map, |
universe@691 | 1124 | char const *key |
universe@691 | 1125 | ) { |
universe@856 | 1126 | return map->cl->remove(map, cx_hash_key_str(key), !map->collection.store_pointer); |
universe@691 | 1127 | } |
universe@691 | 1128 | |
universe@691 | 1129 | /** |
universe@691 | 1130 | * Removes a key/value-pair from the map by using the key. |
universe@691 | 1131 | * |
universe@691 | 1132 | * This function can be used when the map is storing pointers, |
universe@691 | 1133 | * in order to retrieve the pointer from the map without invoking |
universe@691 | 1134 | * any destructor function. Sometimes you do not want the pointer |
universe@691 | 1135 | * to be returned - in that case (instead of suppressing the "unused |
universe@691 | 1136 | * result" warning) you can use cxMapDetach(). |
universe@691 | 1137 | * |
universe@691 | 1138 | * If this map is not storing pointers, this function behaves like |
universe@691 | 1139 | * cxMapRemove() and returns \c NULL. |
universe@691 | 1140 | * |
universe@691 | 1141 | * @param map the map |
universe@691 | 1142 | * @param key the key |
universe@691 | 1143 | * @return the stored pointer or \c NULL if either the key is not present |
universe@691 | 1144 | * in the map or the map is not storing pointers |
universe@691 | 1145 | * @see cxMapStorePointers() |
universe@691 | 1146 | * @see cxMapDetach() |
universe@691 | 1147 | */ |
universe@691 | 1148 | #define cxMapRemoveAndGet(map, key) _Generic((key), \ |
universe@691 | 1149 | CxHashKey: cx_map_remove_and_get, \ |
universe@691 | 1150 | cxstring: cx_map_remove_and_get_cxstr, \ |
universe@692 | 1151 | cxmutstr: cx_map_remove_and_get_mustr, \ |
universe@694 | 1152 | char*: cx_map_remove_and_get_str, \ |
universe@694 | 1153 | char const*: cx_map_remove_and_get_str) \ |
universe@691 | 1154 | (map, key) |
universe@691 | 1155 | |
universe@691 | 1156 | #endif // __cplusplus |
universe@691 | 1157 | |
universe@691 | 1158 | #endif // UCX_MAP_H |