Mercurial > hg > ucx / file comparison

comparison: src/cx/map.h

src/cx/map.h

changeset 1408
aaa440cd4125
parent 1344
8afaeb395b3c
equal deleted inserted replaced
1407:59290d70434a 1408:aaa440cd4125
377 */ 377 */
378 cx_attr_nodiscard 378 cx_attr_nodiscard
379 cx_attr_export 379 cx_attr_export
380 CxMapIterator cxMapMutIterator(CxMap *map); 380 CxMapIterator cxMapMutIterator(CxMap *map);
381 381
382 #ifdef __cplusplus 382 /**
383 } // end the extern "C" block here, because we want to start overloading 383 * Puts a key/value-pair into the map.
384 cx_attr_nonnull 384 *
385 static inline int cxMapPut( 385 * A possible existing value will be overwritten.
386 CxMap *map, 386 * If destructor functions are specified, they are called for
387 CxHashKey const &key, 387 * the overwritten element.
388 void *value 388 *
389 ) { 389 * If this map is storing pointers, the @p value pointer is written
390 return map->cl->put(map, key, value) == NULL; 390 * to the map. Otherwise, the memory is copied from @p value with
391 } 391 * memcpy().
392 392 *
393 cx_attr_nonnull 393 * The @p key is always copied.
394 static inline int cxMapPut( 394 *
395 CxMap *map, 395 * @param map the map
396 cxstring const &key, 396 * @param key the key
397 void *value 397 * @param value the value
398 ) { 398 * @retval zero success
399 return map->cl->put(map, cx_hash_key_cxstr(key), value) == NULL; 399 * @retval non-zero value on memory allocation failure
400 } 400 * @see cxMapPut()
401
402 cx_attr_nonnull
403 static inline int cxMapPut(
404 CxMap *map,
405 cxmutstr const &key,
406 void *value
407 ) {
408 return map->cl->put(map, cx_hash_key_cxstr(key), value) == NULL;
409 }
410
411 cx_attr_nonnull
412 cx_attr_cstr_arg(2)
413 static inline int cxMapPut(
414 CxMap *map,
415 const char *key,
416 void *value
417 ) {
418 return map->cl->put(map, cx_hash_key_str(key), value) == NULL;
419 }
420
421 cx_attr_nonnull
422 static inline void *cxMapEmplace(
423 CxMap *map,
424 CxHashKey const &key
425 ) {
426 return map->cl->put(map, key, NULL);
427 }
428
429 cx_attr_nonnull
430 static inline void *cxMapEmplace(
431 CxMap *map,
432 cxstring const &key
433 ) {
434 return map->cl->put(map, cx_hash_key_cxstr(key), NULL);
435 }
436
437 cx_attr_nonnull
438 static inline void *cxMapEmplace(
439 CxMap *map,
440 cxmutstr const &key
441 ) {
442 return map->cl->put(map, cx_hash_key_cxstr(key), NULL);
443 }
444
445 cx_attr_nonnull
446 cx_attr_cstr_arg(2)
447 static inline void *cxMapEmplace(
448 CxMap *map,
449 const char *key
450 ) {
451 return map->cl->put(map, cx_hash_key_str(key), NULL);
452 }
453
454 cx_attr_nonnull
455 cx_attr_nodiscard
456 static inline void *cxMapGet(
457 const CxMap *map,
458 CxHashKey const &key
459 ) {
460 return map->cl->get(map, key);
461 }
462
463 cx_attr_nonnull
464 cx_attr_nodiscard
465 static inline void *cxMapGet(
466 const CxMap *map,
467 cxstring const &key
468 ) {
469 return map->cl->get(map, cx_hash_key_cxstr(key));
470 }
471
472 cx_attr_nonnull
473 cx_attr_nodiscard
474 static inline void *cxMapGet(
475 const CxMap *map,
476 cxmutstr const &key
477 ) {
478 return map->cl->get(map, cx_hash_key_cxstr(key));
479 }
480
481 cx_attr_nonnull
482 cx_attr_nodiscard
483 cx_attr_cstr_arg(2)
484 static inline void *cxMapGet(
485 const CxMap *map,
486 const char *key
487 ) {
488 return map->cl->get(map, cx_hash_key_str(key));
489 }
490
491 cx_attr_nonnull
492 static inline int cxMapRemove(
493 CxMap *map,
494 CxHashKey const &key
495 ) {
496 return map->cl->remove(map, key, nullptr);
497 }
498
499 cx_attr_nonnull
500 static inline int cxMapRemove(
501 CxMap *map,
502 cxstring const &key
503 ) {
504 return map->cl->remove(map, cx_hash_key_cxstr(key), nullptr);
505 }
506
507 cx_attr_nonnull
508 static inline int cxMapRemove(
509 CxMap *map,
510 cxmutstr const &key
511 ) {
512 return map->cl->remove(map, cx_hash_key_cxstr(key), nullptr);
513 }
514
515 cx_attr_nonnull
516 cx_attr_cstr_arg(2)
517 static inline int cxMapRemove(
518 CxMap *map,
519 const char *key
520 ) {
521 return map->cl->remove(map, cx_hash_key_str(key), nullptr);
522 }
523
524 cx_attr_nonnull
525 cx_attr_access_w(3)
526 static inline int cxMapRemoveAndGet(
527 CxMap *map,
528 CxHashKey key,
529 void *targetbuf
530 ) {
531 return map->cl->remove(map, key, targetbuf);
532 }
533
534 cx_attr_nonnull
535 cx_attr_access_w(3)
536 static inline int cxMapRemoveAndGet(
537 CxMap *map,
538 cxstring key,
539 void *targetbuf
540 ) {
541 return map->cl->remove(map, cx_hash_key_cxstr(key), targetbuf);
542 }
543
544 cx_attr_nonnull
545 cx_attr_access_w(3)
546 static inline int cxMapRemoveAndGet(
547 CxMap *map,
548 cxmutstr key,
549 void *targetbuf
550 ) {
551 return map->cl->remove(map, cx_hash_key_cxstr(key), targetbuf);
552 }
553
554 cx_attr_nonnull
555 cx_attr_access_w(3)
556 cx_attr_cstr_arg(2)
557 static inline int cxMapRemoveAndGet(
558 CxMap *map,
559 const char *key,
560 void *targetbuf
561 ) {
562 return map->cl->remove(map, cx_hash_key_str(key), targetbuf);
563 }
564
565 #else // __cplusplus
566
567 /**
568 * @copydoc cxMapPut()
569 */ 401 */
570 cx_attr_nonnull 402 cx_attr_nonnull
571 static inline int cx_map_put( 403 static inline int cx_map_put(
572 CxMap *map, 404 CxMap *map,
573 CxHashKey key, 405 CxHashKey key,
575 ) { 407 ) {
576 return map->cl->put(map, key, value) == NULL; 408 return map->cl->put(map, key, value) == NULL;
577 } 409 }
578 410
579 /** 411 /**
580 * @copydoc cxMapPut()
581 */
582 cx_attr_nonnull
583 static inline int cx_map_put_cxstr(
584 CxMap *map,
585 cxstring key,
586 void *value
587 ) {
588 return map->cl->put(map, cx_hash_key_cxstr(key), value) == NULL;
589 }
590
591 /**
592 * @copydoc cxMapPut()
593 */
594 cx_attr_nonnull
595 static inline int cx_map_put_mustr(
596 CxMap *map,
597 cxmutstr key,
598 void *value
599 ) {
600 return map->cl->put(map, cx_hash_key_cxstr(key), value) == NULL;
601 }
602
603 /**
604 * @copydoc cxMapPut()
605 */
606 cx_attr_nonnull
607 cx_attr_cstr_arg(2)
608 static inline int cx_map_put_str(
609 CxMap *map,
610 const char *key,
611 void *value
612 ) {
613 return map->cl->put(map, cx_hash_key_str(key), value) == NULL;
614 }
615
616 /**
617 * Puts a key/value-pair into the map. 412 * Puts a key/value-pair into the map.
618 * 413 *
619 * A possible existing value will be overwritten. 414 * A possible existing value will be overwritten.
620 * If destructor functions are specified, they are called for 415 * If destructor functions are specified, they are called for
621 * the overwritten element. 416 * the overwritten element.
625 * memcpy(). 420 * memcpy().
626 * 421 *
627 * The @p key is always copied. 422 * The @p key is always copied.
628 * 423 *
629 * @param map (@c CxMap*) the map 424 * @param map (@c CxMap*) the map
630 * @param key (@c CxHashKey, @c char*, @c cxstring, or @c cxmutstr) the key 425 * @param key (any supported key type) the key
631 * @param value (@c void*) the value 426 * @param value (@c void*) the value
632 * @retval zero success 427 * @retval zero success
633 * @retval non-zero value on memory allocation failure 428 * @retval non-zero value on memory allocation failure
634 */ 429 * @see CX_HASH_KEY()
635 #define cxMapPut(map, key, value) _Generic((key), \ 430 */
636 CxHashKey: cx_map_put, \ 431 #define cxMapPut(map, key, value) cx_map_put(map, CX_HASH_KEY(key), value)
637 cxstring: cx_map_put_cxstr, \ 432
638 cxmutstr: cx_map_put_mustr, \ 433 /**
639 char*: cx_map_put_str, \ 434 * Allocates memory for a value in the map associated with the specified key.
640 const char*: cx_map_put_str) \ 435 *
641 (map, key, value) 436 * A possible existing value will be overwritten.
642 437 * If destructor functions are specified, they are called for
643 /** 438 * the overwritten element.
644 * @copydoc cxMapEmplace() 439 *
440 * If the map is storing pointers, this function returns a @c void** pointer,
441 * meaning a pointer to that pointer.
442 *
443 * The @p key is always copied.
444 *
445 * @param map the map
446 * @param key the key
447 * @return the pointer to the allocated memory or @c NULL if allocation fails
448 * @retval zero success
449 * @retval non-zero value on memory allocation failure
450 * @see cxMapEmplace()
645 */ 451 */
646 cx_attr_nonnull 452 cx_attr_nonnull
647 static inline void *cx_map_emplace( 453 static inline void *cx_map_emplace(
648 CxMap *map, 454 CxMap *map,
649 CxHashKey key 455 CxHashKey key
650 ) { 456 ) {
651 return map->cl->put(map, key, NULL); 457 return map->cl->put(map, key, NULL);
652 } 458 }
653 459
654 /** 460 /**
655 * @copydoc cxMapEmplace()
656 */
657 cx_attr_nonnull
658 static inline void *cx_map_emplace_cxstr(
659 CxMap *map,
660 cxstring key
661 ) {
662 return map->cl->put(map, cx_hash_key_cxstr(key), NULL);
663 }
664
665 /**
666 * @copydoc cxMapEmplace()
667 */
668 cx_attr_nonnull
669 static inline void *cx_map_emplace_mustr(
670 CxMap *map,
671 cxmutstr key
672 ) {
673 return map->cl->put(map, cx_hash_key_cxstr(key), NULL);
674 }
675
676 /**
677 * @copydoc cxMapEmplace()
678 */
679 cx_attr_nonnull
680 cx_attr_cstr_arg(2)
681 static inline void *cx_map_emplace_str(
682 CxMap *map,
683 const char *key
684 ) {
685 return map->cl->put(map, cx_hash_key_str(key), NULL);
686 }
687
688 /**
689 * Allocates memory for a value in the map associated with the specified key. 461 * Allocates memory for a value in the map associated with the specified key.
690 * 462 *
691 * A possible existing value will be overwritten. 463 * A possible existing value will be overwritten.
692 * If destructor functions are specified, they are called for 464 * If destructor functions are specified, they are called for
693 * the overwritten element. 465 * the overwritten element.
696 * meaning a pointer to that pointer. 468 * meaning a pointer to that pointer.
697 * 469 *
698 * The @p key is always copied. 470 * The @p key is always copied.
699 * 471 *
700 * @param map (@c CxMap*) the map 472 * @param map (@c CxMap*) the map
701 * @param key (@c CxHashKey, @c char*, @c cxstring, or @c cxmutstr) the key 473 * @param key (any supported key type) the key
702 * @return the pointer to the allocated memory or @c NULL if allocation fails 474 * @return the pointer to the allocated memory or @c NULL if allocation fails
703 * @retval zero success 475 * @retval zero success
704 * @retval non-zero value on memory allocation failure 476 * @retval non-zero value on memory allocation failure
705 */ 477 * @see CX_HASH_KEY()
706 #define cxMapEmplace(map, key) _Generic((key), \ 478 */
707 CxHashKey: cx_map_emplace, \ 479 #define cxMapEmplace(map, key) cx_map_emplace(map, CX_HASH_KEY(key))
708 cxstring: cx_map_emplace_cxstr, \ 480
709 cxmutstr: cx_map_emplace_mustr, \ 481 /**
710 char*: cx_map_emplace_str, \ 482 * Retrieves a value by using a key.
711 const char*: cx_map_emplace_str) \ 483 *
712 (map, key) 484 * If this map is storing pointers, the stored pointer is returned.
713 485 * Otherwise, a pointer to the element within the map's memory
714 /** 486 * is returned (which is valid as long as the element stays in the map).
715 * @copydoc cxMapGet() 487 *
488 * @param map the map
489 * @param key the key
490 * @return the value
491 * @see cxMapGet()
716 */ 492 */
717 cx_attr_nonnull 493 cx_attr_nonnull
718 cx_attr_nodiscard 494 cx_attr_nodiscard
719 static inline void *cx_map_get( 495 static inline void *cx_map_get(
720 const CxMap *map, 496 const CxMap *map,
722 ) { 498 ) {
723 return map->cl->get(map, key); 499 return map->cl->get(map, key);
724 } 500 }
725 501
726 /** 502 /**
727 * @copydoc cxMapGet()
728 */
729 cx_attr_nonnull
730 cx_attr_nodiscard
731 static inline void *cx_map_get_cxstr(
732 const CxMap *map,
733 cxstring key
734 ) {
735 return map->cl->get(map, cx_hash_key_cxstr(key));
736 }
737
738 /**
739 * @copydoc cxMapGet()
740 */
741 cx_attr_nonnull
742 cx_attr_nodiscard
743 static inline void *cx_map_get_mustr(
744 const CxMap *map,
745 cxmutstr key
746 ) {
747 return map->cl->get(map, cx_hash_key_cxstr(key));
748 }
749
750 /**
751 * @copydoc cxMapGet()
752 */
753 cx_attr_nonnull
754 cx_attr_nodiscard
755 cx_attr_cstr_arg(2)
756 static inline void *cx_map_get_str(
757 const CxMap *map,
758 const char *key
759 ) {
760 return map->cl->get(map, cx_hash_key_str(key));
761 }
762
763 /**
764 * Retrieves a value by using a key. 503 * Retrieves a value by using a key.
765 * 504 *
766 * If this map is storing pointers, the stored pointer is returned. 505 * If this map is storing pointers, the stored pointer is returned.
767 * Otherwise, a pointer to the element within the map's memory 506 * Otherwise, a pointer to the element within the map's memory
768 * is returned (which is valid as long as the element stays in the map). 507 * is returned (which is valid as long as the element stays in the map).
769 * 508 *
770 * @param map (@c CxMap*) the map 509 * @param map (@c CxMap*) the map
771 * @param key (@c CxHashKey, @c char*, @c cxstring, or @c cxmutstr) the key 510 * @param key (any supported key type) the key
772 * @return (@c void*) the value 511 * @return (@c void*) the value
773 */ 512 * @see CX_HASH_KEY()
774 #define cxMapGet(map, key) _Generic((key), \ 513 */
775 CxHashKey: cx_map_get, \ 514 #define cxMapGet(map, key) cx_map_get(map, CX_HASH_KEY(key))
776 cxstring: cx_map_get_cxstr, \ 515
777 cxmutstr: cx_map_get_mustr, \ 516 /**
778 char*: cx_map_get_str, \ 517 * Removes a key/value-pair from the map by using the key.
779 const char*: cx_map_get_str) \ 518 *
780 (map, key) 519 * Invokes the destructor functions, if any, on the removed element, if and only if the
781 520 * @p targetbuf is @c NULL.
782 /** 521 *
783 * @copydoc cxMapRemove() 522 * @param map the map
784 */ 523 * @param key the key
785 cx_attr_nonnull 524 * @param targetbuf the optional buffer where the removed element shall be copied to
525 * @retval zero success
526 * @retval non-zero the key was not found
527 *
528 * @see cxMapRemove()
529 * @see cxMapRemoveAndGet()
530 */
531 cx_attr_nonnull_arg(1)
786 static inline int cx_map_remove( 532 static inline int cx_map_remove(
787 CxMap *map,
788 CxHashKey key
789 ) {
790 return map->cl->remove(map, key, NULL);
791 }
792
793 /**
794 * @copydoc cxMapRemove()
795 */
796 cx_attr_nonnull
797 static inline int cx_map_remove_cxstr(
798 CxMap *map,
799 cxstring key
800 ) {
801 return map->cl->remove(map, cx_hash_key_cxstr(key), NULL);
802 }
803
804 /**
805 * @copydoc cxMapRemove()
806 */
807 cx_attr_nonnull
808 static inline int cx_map_remove_mustr(
809 CxMap *map,
810 cxmutstr key
811 ) {
812 return map->cl->remove(map, cx_hash_key_cxstr(key), NULL);
813 }
814
815 /**
816 * @copydoc cxMapRemove()
817 */
818 cx_attr_nonnull
819 cx_attr_cstr_arg(2)
820 static inline int cx_map_remove_str(
821 CxMap *map,
822 const char *key
823 ) {
824 return map->cl->remove(map, cx_hash_key_str(key), NULL);
825 }
826
827 /**
828 * Removes a key/value-pair from the map by using the key.
829 *
830 * Always invokes the destructors functions, if any, on the removed element.
831 *
832 * @param map (@c CxMap*) the map
833 * @param key (@c CxHashKey, @c char*, @c cxstring, or @c cxmutstr) the key
834 * @retval zero success
835 * @retval non-zero the key was not found
836 *
837 * @see cxMapRemoveAndGet()
838 */
839 #define cxMapRemove(map, key) _Generic((key), \
840 CxHashKey: cx_map_remove, \
841 cxstring: cx_map_remove_cxstr, \
842 cxmutstr: cx_map_remove_mustr, \
843 char*: cx_map_remove_str, \
844 const char*: cx_map_remove_str) \
845 (map, key)
846
847 /**
848 * @copydoc cxMapRemoveAndGet()
849 */
850 cx_attr_nonnull
851 cx_attr_access_w(3)
852 static inline int cx_map_remove_and_get(
853 CxMap *map, 533 CxMap *map,
854 CxHashKey key, 534 CxHashKey key,
855 void *targetbuf 535 void *targetbuf
856 ) { 536 ) {
857 return map->cl->remove(map, key, targetbuf); 537 return map->cl->remove(map, key, targetbuf);
858 } 538 }
859 539
860 /** 540 /**
861 * @copydoc cxMapRemoveAndGet() 541 * Removes a key/value-pair from the map by using the key.
862 */ 542 *
863 cx_attr_nonnull 543 * Always invokes the destructor functions, if any, on the removed element.
864 cx_attr_access_w(3) 544 *
865 static inline int cx_map_remove_and_get_cxstr( 545 * @param map (@c CxMap*) the map
866 CxMap *map, 546 * @param key (any supported key type) the key
867 cxstring key, 547 * @retval zero success
868 void *targetbuf 548 * @retval non-zero the key was not found
869 ) { 549 *
870 return map->cl->remove(map, cx_hash_key_cxstr(key), targetbuf); 550 * @see cxMapRemoveAndGet()
871 } 551 * @see CX_HASH_KEY()
872 552 */
873 /** 553 #define cxMapRemove(map, key) cx_map_remove(map, CX_HASH_KEY(key), NULL)
874 * @copydoc cxMapRemoveAndGet()
875 */
876 cx_attr_nonnull
877 cx_attr_access_w(3)
878 static inline int cx_map_remove_and_get_mustr(
879 CxMap *map,
880 cxmutstr key,
881 void *targetbuf
882 ) {
883 return map->cl->remove(map, cx_hash_key_cxstr(key), targetbuf);
884 }
885
886 /**
887 * @copydoc cxMapRemoveAndGet()
888 */
889 cx_attr_nonnull
890 cx_attr_access_w(3)
891 cx_attr_cstr_arg(2)
892 static inline int cx_map_remove_and_get_str(
893 CxMap *map,
894 const char *key,
895 void *targetbuf
896 ) {
897 return map->cl->remove(map, cx_hash_key_str(key), targetbuf);
898 }
899 554
900 /** 555 /**
901 * Removes a key/value-pair from the map by using the key. 556 * Removes a key/value-pair from the map by using the key.
902 * 557 *
903 * This function will copy the contents of the removed element 558 * This function will copy the contents of the removed element
907 * 562 *
908 * If this map is storing pointers, the element is the pointer itself 563 * If this map is storing pointers, the element is the pointer itself
909 * and not the object it points to. 564 * and not the object it points to.
910 * 565 *
911 * @param map (@c CxMap*) the map 566 * @param map (@c CxMap*) the map
912 * @param key (@c CxHashKey, @c char*, @c cxstring, or @c cxmutstr) the key 567 * @param key (any supported key type) the key
913 * @param targetbuf (@c void*) the buffer where the element shall be copied to 568 * @param targetbuf (@c void*) the buffer where the element shall be copied to
914 * @retval zero success 569 * @retval zero success
915 * @retval non-zero the key was not found 570 * @retval non-zero the key was not found
916 * 571 *
917 * @see cxMapRemove() 572 * @see cxMapRemove()
918 */ 573 * @see CX_HASH_KEY()
919 #define cxMapRemoveAndGet(map, key, targetbuf) _Generic((key), \ 574 */
920 CxHashKey: cx_map_remove_and_get, \ 575 #define cxMapRemoveAndGet(map, key, targetbuf) cx_map_remove(map, CX_HASH_KEY(key), targetbuf)
921 cxstring: cx_map_remove_and_get_cxstr, \
922 cxmutstr: cx_map_remove_and_get_mustr, \
923 char*: cx_map_remove_and_get_str, \
924 const char*: cx_map_remove_and_get_str) \
925 (map, key, targetbuf)
926
927 #endif // __cplusplus
928 576
929 #endif // UCX_MAP_H 577 #endif // UCX_MAP_H

Mercurial Repository: ucx

mercurial