ucx/cx/map.h

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