comparison: ucx/cx/map.h
ucx/cx/map.h
- changeset 943
- 9b5948aa5b90
- parent 870
- e167cf006213
equal
deleted
inserted
replaced
| 942:488178e3e328 | 943:9b5948aa5b90 |
|---|---|
| 39 #include "common.h" | 39 #include "common.h" |
| 40 #include "collection.h" | 40 #include "collection.h" |
| 41 #include "string.h" | 41 #include "string.h" |
| 42 #include "hash_key.h" | 42 #include "hash_key.h" |
| 43 | 43 |
| 44 #ifndef UCX_LIST_H | |
| 45 // forward-declare CxList | |
| 46 typedef struct cx_list_s CxList; | |
| 47 #endif | |
| 48 | |
| 44 #ifdef __cplusplus | 49 #ifdef __cplusplus |
| 45 extern "C" { | 50 extern "C" { |
| 46 #endif | 51 #endif |
| 47 | 52 |
| 48 /** Type for the UCX map. */ | 53 /** Type for the UCX map. */ |
| 402 * Otherwise, a pointer to the element within the map's memory | 407 * Otherwise, a pointer to the element within the map's memory |
| 403 * is returned (which is valid as long as the element stays in the map). | 408 * is returned (which is valid as long as the element stays in the map). |
| 404 * | 409 * |
| 405 * @param map (@c CxMap*) the map | 410 * @param map (@c CxMap*) the map |
| 406 * @param key (any supported key type) the key | 411 * @param key (any supported key type) the key |
| 407 * @return (@c void*) the value | 412 * @return (@c void*) the value or @c NULL when no value with that @p key exists |
| 408 * @see CX_HASH_KEY() | 413 * @see CX_HASH_KEY() |
| 409 */ | 414 */ |
| 410 #define cxMapGet(map, key) cx_map_get(map, CX_HASH_KEY(key)) | 415 #define cxMapGet(map, key) cx_map_get(map, CX_HASH_KEY(key)) |
| 416 | |
| 417 /** | |
| 418 * Checks if a map contains a specific key. | |
| 419 * | |
| 420 * @param map (@c CxMap*) the map | |
| 421 * @param key (any supported key type) the key | |
| 422 * @retval true if the key exists in the map | |
| 423 * @retval false if the key does not exist in the map | |
| 424 * @see CX_HASH_KEY() | |
| 425 */ | |
| 426 #define cxMapContains(map, key) (cxMapGet(map, key) != NULL) | |
| 411 | 427 |
| 412 /** | 428 /** |
| 413 * Removes a key/value-pair from the map by using the key. | 429 * Removes a key/value-pair from the map by using the key. |
| 414 * | 430 * |
| 415 * Invokes the destructor functions, if any, on the removed element if and only if the | 431 * Invokes the destructor functions, if any, on the removed element if and only if the |
| 462 * @see cxMapRemove() | 478 * @see cxMapRemove() |
| 463 * @see CX_HASH_KEY() | 479 * @see CX_HASH_KEY() |
| 464 */ | 480 */ |
| 465 #define cxMapRemoveAndGet(map, key, targetbuf) cx_map_remove(map, CX_HASH_KEY(key), targetbuf) | 481 #define cxMapRemoveAndGet(map, key, targetbuf) cx_map_remove(map, CX_HASH_KEY(key), targetbuf) |
| 466 | 482 |
| 483 | |
| 484 /** | |
| 485 * Performs a deep clone of one map into another. | |
| 486 * | |
| 487 * If the destination map already contains entries, the cloned entries | |
| 488 * are added to that map, possibly overwriting existing elements when | |
| 489 * the keys already exist. | |
| 490 * | |
| 491 * When elements in the destination map need to be replaced, any destructor | |
| 492 * function is called on the replaced elements before replacing them. | |
| 493 * | |
| 494 * @attention If the cloned elements need to be destroyed by a destructor | |
| 495 * function, you must make sure that the destination map also uses this | |
| 496 * destructor function. | |
| 497 * | |
| 498 * @param dst the destination map | |
| 499 * @param src the source map | |
| 500 * @param clone_func the clone function for the values | |
| 501 * @param clone_allocator the allocator that is passed to the clone function | |
| 502 * @param data optional additional data that is passed to the clone function | |
| 503 * @retval zero when all elements were successfully cloned | |
| 504 * @retval non-zero when an allocation error occurred | |
| 505 */ | |
| 506 cx_attr_nonnull_arg(1, 2, 3) | |
| 507 CX_EXPORT int cxMapClone(CxMap *dst, const CxMap *src, | |
| 508 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data); | |
| 509 | |
| 510 | |
| 511 /** | |
| 512 * Clones entries of a map if their key is not present in another map. | |
| 513 * | |
| 514 * @param dst the destination map | |
| 515 * @param minuend the map to subtract the entries from | |
| 516 * @param subtrahend the map containing the elements to be subtracted | |
| 517 * @param clone_func the clone function for the values | |
| 518 * @param clone_allocator the allocator that is passed to the clone function | |
| 519 * @param data optional additional data that is passed to the clone function | |
| 520 * @retval zero when the elements were successfully cloned | |
| 521 * @retval non-zero when an allocation error occurred | |
| 522 */ | |
| 523 cx_attr_nonnull_arg(1, 2, 3, 4) | |
| 524 CX_EXPORT int cxMapDifference(CxMap *dst, const CxMap *minuend, const CxMap *subtrahend, | |
| 525 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data); | |
| 526 | |
| 527 /** | |
| 528 * Clones entries of a map if their key is not present in a list. | |
| 529 * | |
| 530 * Note that the list must contain keys of type @c CxKey | |
| 531 * (or pointers to such keys) and must use @c cx_hash_key_cmp | |
| 532 * as the compare function. | |
| 533 * Generic key types cannot be processed in this case. | |
| 534 * | |
| 535 * @param dst the destination map | |
| 536 * @param src the source map | |
| 537 * @param keys the list of @c CxKey items | |
| 538 * @param clone_func the clone function for the values | |
| 539 * @param clone_allocator the allocator that is passed to the clone function | |
| 540 * @param data optional additional data that is passed to the clone function | |
| 541 * @retval zero when the elements were successfully cloned | |
| 542 * @retval non-zero when an allocation error occurred | |
| 543 */ | |
| 544 cx_attr_nonnull_arg(1, 2, 3, 4) | |
| 545 CX_EXPORT int cxMapListDifference(CxMap *dst, const CxMap *src, const CxList *keys, | |
| 546 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data); | |
| 547 | |
| 548 | |
| 549 /** | |
| 550 * Clones entries of a map only if their key is present in another map. | |
| 551 * | |
| 552 * @param dst the destination map | |
| 553 * @param src the map to clone the entries from | |
| 554 * @param other the map to check for existence of the keys | |
| 555 * @param clone_func the clone function for the values | |
| 556 * @param clone_allocator the allocator that is passed to the clone function | |
| 557 * @param data optional additional data that is passed to the clone function | |
| 558 * @retval zero when the elements were successfully cloned | |
| 559 * @retval non-zero when an allocation error occurred | |
| 560 */ | |
| 561 cx_attr_nonnull_arg(1, 2, 3, 4) | |
| 562 CX_EXPORT int cxMapIntersection(CxMap *dst, const CxMap *src, const CxMap *other, | |
| 563 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data); | |
| 564 | |
| 565 /** | |
| 566 * Clones entries of a map only if their key is present in a list. | |
| 567 * | |
| 568 * Note that the list must contain keys of type @c CxKey | |
| 569 * (or pointers to such keys) and must use @c cx_hash_key_cmp | |
| 570 * as the compare function. | |
| 571 * Generic key types cannot be processed in this case. | |
| 572 * | |
| 573 * @param dst the destination map | |
| 574 * @param src the source map | |
| 575 * @param keys the list of @c CxKey items | |
| 576 * @param clone_func the clone function for the values | |
| 577 * @param clone_allocator the allocator that is passed to the clone function | |
| 578 * @param data optional additional data that is passed to the clone function | |
| 579 * @retval zero when the elements were successfully cloned | |
| 580 * @retval non-zero when an allocation error occurred | |
| 581 */ | |
| 582 cx_attr_nonnull_arg(1, 2, 3, 4) | |
| 583 CX_EXPORT int cxMapListIntersection(CxMap *dst, const CxMap *src, const CxList *keys, | |
| 584 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data); | |
| 585 | |
| 586 /** | |
| 587 * Clones entries into a map if their key does not exist yet. | |
| 588 * | |
| 589 * If you want to calculate the union of two maps into a fresh new map, | |
| 590 * you can proceed as follows: | |
| 591 * 1. Clone the first map into a fresh, empty map. | |
| 592 * 2. Use this function to clone the second map into the result from step 1. | |
| 593 * | |
| 594 * @param dst the destination map | |
| 595 * @param src the map to clone the entries from | |
| 596 * @param clone_func the clone function for the values | |
| 597 * @param clone_allocator the allocator that is passed to the clone function | |
| 598 * @param data optional additional data that is passed to the clone function | |
| 599 * @retval zero when the elements were successfully cloned | |
| 600 * @retval non-zero when an allocation error occurred | |
| 601 */ | |
| 602 cx_attr_nonnull_arg(1, 2, 3) | |
| 603 CX_EXPORT int cxMapUnion(CxMap *dst, const CxMap *src, | |
| 604 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data); | |
| 605 | |
| 606 /** | |
| 607 * Performs a shallow clone of one map into another. | |
| 608 * | |
| 609 * This function uses the default allocator, if needed, and performs | |
| 610 * shallow clones with @c memcpy(). | |
| 611 * | |
| 612 * If the destination map already contains entries, the cloned entries | |
| 613 * are added to that map, possibly overwriting existing elements when | |
| 614 * the keys already exist. | |
| 615 * | |
| 616 * When elements in the destination map need to be replaced, any destructor | |
| 617 * function is called on the replaced elements before replacing them. | |
| 618 * | |
| 619 * @attention If the cloned elements need to be destroyed by a destructor | |
| 620 * function, you must make sure that the destination map also uses this | |
| 621 * destructor function. | |
| 622 * | |
| 623 * @param dst the destination map | |
| 624 * @param src the source map | |
| 625 * @retval zero when all elements were successfully cloned | |
| 626 * @retval non-zero when an allocation error occurred | |
| 627 * @see cxMapClone() | |
| 628 */ | |
| 629 cx_attr_nonnull | |
| 630 CX_EXPORT int cxMapCloneSimple(CxMap *dst, const CxMap *src); | |
| 631 | |
| 632 /** | |
| 633 * Clones entries of a map if their key is not present in another map. | |
| 634 * | |
| 635 * This function uses the default allocator, if needed, and performs | |
| 636 * shallow clones with @c memcpy(). | |
| 637 * | |
| 638 * @param dst the destination map | |
| 639 * @param minuend the map to subtract the entries from | |
| 640 * @param subtrahend the map containing the elements to be subtracted | |
| 641 * @retval zero when the elements were successfully cloned | |
| 642 * @retval non-zero when an allocation error occurred | |
| 643 */ | |
| 644 cx_attr_nonnull | |
| 645 CX_EXPORT int cxMapDifferenceSimple(CxMap *dst, const CxMap *minuend, const CxMap *subtrahend); | |
| 646 | |
| 647 /** | |
| 648 * Clones entries of a map if their key is not present in a list. | |
| 649 * | |
| 650 * This function uses the default allocator, if needed, and performs | |
| 651 * shallow clones with @c memcpy(). | |
| 652 * | |
| 653 * Note that the list must contain keys of type @c CxKey | |
| 654 * (or pointers to such keys) and must use @c cx_hash_key_cmp | |
| 655 * as the compare function. | |
| 656 * Generic key types cannot be processed in this case. | |
| 657 * | |
| 658 * @param dst the destination map | |
| 659 * @param src the source map | |
| 660 * @param keys the list of @c CxKey items | |
| 661 * @retval zero when the elements were successfully cloned | |
| 662 * @retval non-zero when an allocation error occurred | |
| 663 * @see cxMapListDifference() | |
| 664 */ | |
| 665 cx_attr_nonnull | |
| 666 CX_EXPORT int cxMapListDifferenceSimple(CxMap *dst, const CxMap *src, const CxList *keys); | |
| 667 | |
| 668 | |
| 669 /** | |
| 670 * Clones entries of a map only if their key is present in another map. | |
| 671 * | |
| 672 * This function uses the default allocator, if needed, and performs | |
| 673 * shallow clones with @c memcpy(). | |
| 674 * | |
| 675 * @param dst the destination map | |
| 676 * @param src the map to clone the entries from | |
| 677 * @param other the map to check for existence of the keys | |
| 678 * @retval zero when the elements were successfully cloned | |
| 679 * @retval non-zero when an allocation error occurred | |
| 680 */ | |
| 681 cx_attr_nonnull | |
| 682 CX_EXPORT int cxMapIntersectionSimple(CxMap *dst, const CxMap *src, const CxMap *other); | |
| 683 | |
| 684 /** | |
| 685 * Clones entries of a map only if their key is present in a list. | |
| 686 * | |
| 687 * This function uses the default allocator, if needed, and performs | |
| 688 * shallow clones with @c memcpy(). | |
| 689 * | |
| 690 * Note that the list must contain keys of type @c CxKey | |
| 691 * (or pointers to such keys) and must use @c cx_hash_key_cmp | |
| 692 * as the compare function. | |
| 693 * Generic key types cannot be processed in this case. | |
| 694 * | |
| 695 * @param dst the destination map | |
| 696 * @param src the source map | |
| 697 * @param keys the list of @c CxKey items | |
| 698 * @retval zero when the elements were successfully cloned | |
| 699 * @retval non-zero when an allocation error occurred | |
| 700 */ | |
| 701 cx_attr_nonnull | |
| 702 CX_EXPORT int cxMapListIntersectionSimple(CxMap *dst, const CxMap *src, const CxList *keys); | |
| 703 | |
| 704 /** | |
| 705 * Clones entries into a map if their key does not exist yet. | |
| 706 * | |
| 707 * This function uses the default allocator, if needed, and performs | |
| 708 * shallow clones with @c memcpy(). | |
| 709 * | |
| 710 * If you want to calculate the union of two maps into a fresh new map, | |
| 711 * you can proceed as follows: | |
| 712 * 1. Clone the first map into a fresh, empty map. | |
| 713 * 2. Use this function to clone the second map into the result from step 1. | |
| 714 * | |
| 715 * @param dst the destination map | |
| 716 * @param src the map to clone the entries from | |
| 717 * @retval zero when the elements were successfully cloned | |
| 718 * @retval non-zero when an allocation error occurred | |
| 719 */ | |
| 720 cx_attr_nonnull | |
| 721 CX_EXPORT int cxMapUnionSimple(CxMap *dst, const CxMap *src); | |
| 722 | |
| 467 #ifdef __cplusplus | 723 #ifdef __cplusplus |
| 468 } // extern "C" | 724 } // extern "C" |
| 469 #endif | 725 #endif |
| 470 | 726 |
| 471 #endif // UCX_MAP_H | 727 #endif // UCX_MAP_H |
