comparison: ucx/cx/map.h
ucx/cx/map.h
- changeset 1016
- ccde46662db7
- parent 943
- 9b5948aa5b90
equal
deleted
inserted
replaced
| 1015:b459361d98ad | 1016:ccde46662db7 |
|---|---|
| 181 | 181 |
| 182 /** | 182 /** |
| 183 * Add or overwrite an element. | 183 * Add or overwrite an element. |
| 184 * If the @p value is @c NULL, the implementation | 184 * If the @p value is @c NULL, the implementation |
| 185 * shall only allocate memory instead of adding an existing value to the map. | 185 * shall only allocate memory instead of adding an existing value to the map. |
| 186 * Returns a pointer to the allocated memory or @c NULL if allocation fails. | 186 * Returns a map entry where the pointer to the key is @c NULL if allocation fails. |
| 187 */ | 187 */ |
| 188 void *(*put)(CxMap *map, CxHashKey key, void *value); | 188 CxMapEntry (*put)(CxMap *map, CxHashKey key, void *value); |
| 189 | 189 |
| 190 /** | 190 /** |
| 191 * Returns an element. | 191 * Returns an element. |
| 192 */ | 192 */ |
| 193 void *(*get)(const CxMap *map, CxHashKey key); | 193 void *(*get)(const CxMap *map, CxHashKey key); |
| 355 * The @p key is always copied. | 355 * The @p key is always copied. |
| 356 * | 356 * |
| 357 * @param map the map | 357 * @param map the map |
| 358 * @param key the key | 358 * @param key the key |
| 359 * @return the pointer to the allocated memory or @c NULL if allocation fails | 359 * @return the pointer to the allocated memory or @c NULL if allocation fails |
| 360 * @retval zero success | |
| 361 * @retval non-zero value on memory allocation failure | |
| 362 * @see cxMapEmplace() | 360 * @see cxMapEmplace() |
| 363 */ | 361 */ |
| 364 cx_attr_nonnull | 362 cx_attr_nonnull |
| 365 CX_EXPORT void *cx_map_emplace(CxMap *map, CxHashKey key); | 363 CX_EXPORT void *cx_map_emplace(CxMap *map, CxHashKey key); |
| 366 | 364 |
| 377 * The @p key is always copied. | 375 * The @p key is always copied. |
| 378 * | 376 * |
| 379 * @param map (@c CxMap*) the map | 377 * @param map (@c CxMap*) the map |
| 380 * @param key (any supported key type) the key | 378 * @param key (any supported key type) the key |
| 381 * @return the pointer to the allocated memory or @c NULL if allocation fails | 379 * @return the pointer to the allocated memory or @c NULL if allocation fails |
| 382 * @retval zero success | |
| 383 * @retval non-zero value on memory allocation failure | |
| 384 * @see CX_HASH_KEY() | 380 * @see CX_HASH_KEY() |
| 385 */ | 381 */ |
| 386 #define cxMapEmplace(map, key) cx_map_emplace(map, CX_HASH_KEY(key)) | 382 #define cxMapEmplace(map, key) cx_map_emplace(map, CX_HASH_KEY(key)) |
| 387 | 383 |
| 388 /** | 384 /** |
| 625 * @retval zero when all elements were successfully cloned | 621 * @retval zero when all elements were successfully cloned |
| 626 * @retval non-zero when an allocation error occurred | 622 * @retval non-zero when an allocation error occurred |
| 627 * @see cxMapClone() | 623 * @see cxMapClone() |
| 628 */ | 624 */ |
| 629 cx_attr_nonnull | 625 cx_attr_nonnull |
| 630 CX_EXPORT int cxMapCloneSimple(CxMap *dst, const CxMap *src); | 626 CX_EXPORT int cxMapCloneShallow(CxMap *dst, const CxMap *src); |
| 631 | 627 |
| 632 /** | 628 /** |
| 633 * Clones entries of a map if their key is not present in another map. | 629 * Clones entries of a map if their key is not present in another map. |
| 634 * | 630 * |
| 635 * This function uses the default allocator, if needed, and performs | 631 * This function uses the default allocator, if needed, and performs |
| 640 * @param subtrahend the map containing the elements to be subtracted | 636 * @param subtrahend the map containing the elements to be subtracted |
| 641 * @retval zero when the elements were successfully cloned | 637 * @retval zero when the elements were successfully cloned |
| 642 * @retval non-zero when an allocation error occurred | 638 * @retval non-zero when an allocation error occurred |
| 643 */ | 639 */ |
| 644 cx_attr_nonnull | 640 cx_attr_nonnull |
| 645 CX_EXPORT int cxMapDifferenceSimple(CxMap *dst, const CxMap *minuend, const CxMap *subtrahend); | 641 CX_EXPORT int cxMapDifferenceShallow(CxMap *dst, const CxMap *minuend, const CxMap *subtrahend); |
| 646 | 642 |
| 647 /** | 643 /** |
| 648 * Clones entries of a map if their key is not present in a list. | 644 * Clones entries of a map if their key is not present in a list. |
| 649 * | 645 * |
| 650 * This function uses the default allocator, if needed, and performs | 646 * This function uses the default allocator, if needed, and performs |
| 661 * @retval zero when the elements were successfully cloned | 657 * @retval zero when the elements were successfully cloned |
| 662 * @retval non-zero when an allocation error occurred | 658 * @retval non-zero when an allocation error occurred |
| 663 * @see cxMapListDifference() | 659 * @see cxMapListDifference() |
| 664 */ | 660 */ |
| 665 cx_attr_nonnull | 661 cx_attr_nonnull |
| 666 CX_EXPORT int cxMapListDifferenceSimple(CxMap *dst, const CxMap *src, const CxList *keys); | 662 CX_EXPORT int cxMapListDifferenceShallow(CxMap *dst, const CxMap *src, const CxList *keys); |
| 667 | 663 |
| 668 | 664 |
| 669 /** | 665 /** |
| 670 * Clones entries of a map only if their key is present in another map. | 666 * Clones entries of a map only if their key is present in another map. |
| 671 * | 667 * |
| 677 * @param other the map to check for existence of the keys | 673 * @param other the map to check for existence of the keys |
| 678 * @retval zero when the elements were successfully cloned | 674 * @retval zero when the elements were successfully cloned |
| 679 * @retval non-zero when an allocation error occurred | 675 * @retval non-zero when an allocation error occurred |
| 680 */ | 676 */ |
| 681 cx_attr_nonnull | 677 cx_attr_nonnull |
| 682 CX_EXPORT int cxMapIntersectionSimple(CxMap *dst, const CxMap *src, const CxMap *other); | 678 CX_EXPORT int cxMapIntersectionShallow(CxMap *dst, const CxMap *src, const CxMap *other); |
| 683 | 679 |
| 684 /** | 680 /** |
| 685 * Clones entries of a map only if their key is present in a list. | 681 * Clones entries of a map only if their key is present in a list. |
| 686 * | 682 * |
| 687 * This function uses the default allocator, if needed, and performs | 683 * This function uses the default allocator, if needed, and performs |
| 697 * @param keys the list of @c CxKey items | 693 * @param keys the list of @c CxKey items |
| 698 * @retval zero when the elements were successfully cloned | 694 * @retval zero when the elements were successfully cloned |
| 699 * @retval non-zero when an allocation error occurred | 695 * @retval non-zero when an allocation error occurred |
| 700 */ | 696 */ |
| 701 cx_attr_nonnull | 697 cx_attr_nonnull |
| 702 CX_EXPORT int cxMapListIntersectionSimple(CxMap *dst, const CxMap *src, const CxList *keys); | 698 CX_EXPORT int cxMapListIntersectionShallow(CxMap *dst, const CxMap *src, const CxList *keys); |
| 703 | 699 |
| 704 /** | 700 /** |
| 705 * Clones entries into a map if their key does not exist yet. | 701 * Clones entries into a map if their key does not exist yet. |
| 706 * | 702 * |
| 707 * This function uses the default allocator, if needed, and performs | 703 * This function uses the default allocator, if needed, and performs |
| 716 * @param src the map to clone the entries from | 712 * @param src the map to clone the entries from |
| 717 * @retval zero when the elements were successfully cloned | 713 * @retval zero when the elements were successfully cloned |
| 718 * @retval non-zero when an allocation error occurred | 714 * @retval non-zero when an allocation error occurred |
| 719 */ | 715 */ |
| 720 cx_attr_nonnull | 716 cx_attr_nonnull |
| 721 CX_EXPORT int cxMapUnionSimple(CxMap *dst, const CxMap *src); | 717 CX_EXPORT int cxMapUnionShallow(CxMap *dst, const CxMap *src); |
| 718 | |
| 719 | |
| 720 /** | |
| 721 * Compares the entries of two maps. | |
| 722 * | |
| 723 * @param map the map | |
| 724 * @param other the other map that the first map is compared to | |
| 725 * @retval zero when both maps have the same key sets | |
| 726 * and the values are pairwise equivalent | |
| 727 * @retval negative when the first @p map has fewer keys than the @p other map | |
| 728 * @retval positive when the first @p map has more keys than the @p other map | |
| 729 * @retval non-zero (unspecified whether positive or negative) when the size | |
| 730 * of both maps is equal but a key or a value is different | |
| 731 */ | |
| 732 cx_attr_nonnull | |
| 733 CX_EXPORT int cxMapCompare(const CxMap *map, const CxMap *other); | |
| 722 | 734 |
| 723 #ifdef __cplusplus | 735 #ifdef __cplusplus |
| 724 } // extern "C" | 736 } // extern "C" |
| 725 #endif | 737 #endif |
| 726 | 738 |
