Mercurial > hg > ucx / file comparison

comparison: src/cx/map.h

src/cx/map.h

changeset 1675
36c0fb2b60b2
parent 1604
68b75c091028
equal deleted inserted replaced
1674:8b0f162ac88e 1675:36c0fb2b60b2
44 #ifndef UCX_LIST_H 44 #ifndef UCX_LIST_H
45 // forward-declare CxList 45 // forward-declare CxList
46 typedef struct cx_list_s CxList; 46 typedef struct cx_list_s CxList;
47 #endif 47 #endif
48 48
49 #ifdef __cplusplus
50 extern "C" {
51 #endif
52
53 /** Type for the UCX map. */ 49 /** Type for the UCX map. */
54 typedef struct cx_map_s CxMap; 50 typedef struct cx_map_s CxMap;
55 51
56 /** Type for a map entry. */ 52 /** Type for a map entry. */
57 typedef struct cx_map_entry_s CxMapEntry; 53 typedef struct cx_map_entry_s CxMapEntry;
225 * 221 *
226 * Also calls the content destructor functions for each element, if specified. 222 * Also calls the content destructor functions for each element, if specified.
227 * 223 *
228 * @param map the map to be freed 224 * @param map the map to be freed
229 */ 225 */
230 CX_EXPORT void cxMapFree(CxMap *map); 226 CX_EXTERN
231 227 void cxMapFree(CxMap *map);
232 228
233 /** 229 /**
234 * Clears a map by removing all elements. 230 * Clears a map by removing all elements.
235 * 231 *
236 * Also calls the content destructor functions for each element, if specified. 232 * Also calls the content destructor functions for each element, if specified.
237 * 233 *
238 * @param map the map to be cleared 234 * @param map the map to be cleared
239 */ 235 */
240 cx_attr_nonnull 236 CX_EXTERN CX_NONNULL
241 CX_EXPORT void cxMapClear(CxMap *map); 237 void cxMapClear(CxMap *map);
242 238
243 /** 239 /**
244 * Returns the number of elements in this map. 240 * Returns the number of elements in this map.
245 * 241 *
246 * @param map the map 242 * @param map the map
247 * @return the number of stored elements 243 * @return the number of stored elements
248 */ 244 */
249 cx_attr_nonnull 245 CX_EXTERN CX_NONNULL
250 CX_EXPORT size_t cxMapSize(const CxMap *map); 246 size_t cxMapSize(const CxMap *map);
251 247
252 /** 248 /**
253 * Creates a value iterator for a map. 249 * Creates a value iterator for a map.
254 * 250 *
255 * When the map is storing pointers, those pointers are returned. 251 * When the map is storing pointers, those pointers are returned.
260 * highly depends on the map implementation and may change arbitrarily when the contents change. 256 * highly depends on the map implementation and may change arbitrarily when the contents change.
261 * 257 *
262 * @param map the map to create the iterator for (can be @c NULL) 258 * @param map the map to create the iterator for (can be @c NULL)
263 * @return an iterator for the currently stored values 259 * @return an iterator for the currently stored values
264 */ 260 */
265 cx_attr_nodiscard 261 CX_EXTERN CX_NODISCARD
266 CX_EXPORT CxMapIterator cxMapIteratorValues(const CxMap *map); 262 CxMapIterator cxMapIteratorValues(const CxMap *map);
267 263
268 /** 264 /**
269 * Creates a key iterator for a map. 265 * Creates a key iterator for a map.
270 * 266 *
271 * The elements of the iterator are keys of type CxHashKey, and the pointer returned 267 * The elements of the iterator are keys of type CxHashKey, and the pointer returned
275 * highly depends on the map implementation and may change arbitrarily when the contents change. 271 * highly depends on the map implementation and may change arbitrarily when the contents change.
276 * 272 *
277 * @param map the map to create the iterator for (can be @c NULL) 273 * @param map the map to create the iterator for (can be @c NULL)
278 * @return an iterator for the currently stored keys 274 * @return an iterator for the currently stored keys
279 */ 275 */
280 cx_attr_nodiscard 276 CX_EXTERN CX_NODISCARD
281 CX_EXPORT CxMapIterator cxMapIteratorKeys(const CxMap *map); 277 CxMapIterator cxMapIteratorKeys(const CxMap *map);
282 278
283 /** 279 /**
284 * Creates an iterator for a map. 280 * Creates an iterator for a map.
285 * 281 *
286 * The elements of the iterator are key/value pairs of type CxMapEntry, and the pointer returned 282 * The elements of the iterator are key/value pairs of type CxMapEntry, and the pointer returned
292 * @param map the map to create the iterator for (can be @c NULL) 288 * @param map the map to create the iterator for (can be @c NULL)
293 * @return an iterator for the currently stored entries 289 * @return an iterator for the currently stored entries
294 * @see cxMapIteratorKeys() 290 * @see cxMapIteratorKeys()
295 * @see cxMapIteratorValues() 291 * @see cxMapIteratorValues()
296 */ 292 */
297 cx_attr_nodiscard 293 CX_EXTERN CX_NODISCARD
298 CX_EXPORT CxMapIterator cxMapIterator(const CxMap *map); 294 CxMapIterator cxMapIterator(const CxMap *map);
299 295
300 /** 296 /**
301 * Puts a key/value-pair into the map. 297 * Puts a key/value-pair into the map.
302 * 298 *
303 * A possible existing value will be overwritten. 299 * A possible existing value will be overwritten.
315 * @param value the value 311 * @param value the value
316 * @retval zero success 312 * @retval zero success
317 * @retval non-zero value on memory allocation failure 313 * @retval non-zero value on memory allocation failure
318 * @see cxMapPut() 314 * @see cxMapPut()
319 */ 315 */
320 cx_attr_nonnull 316 CX_EXTERN CX_NONNULL
321 CX_EXPORT int cx_map_put(CxMap *map, CxHashKey key, void *value); 317 int cx_map_put(CxMap *map, CxHashKey key, void *value);
322 318
323 /** 319 /**
324 * Puts a key/value-pair into the map. 320 * Puts a key/value-pair into the map.
325 * 321 *
326 * A possible existing value will be overwritten. 322 * A possible existing value will be overwritten.
357 * @param map the map 353 * @param map the map
358 * @param key the key 354 * @param key the key
359 * @return the pointer to the allocated memory or @c NULL if allocation fails 355 * @return the pointer to the allocated memory or @c NULL if allocation fails
360 * @see cxMapEmplace() 356 * @see cxMapEmplace()
361 */ 357 */
362 cx_attr_nonnull 358 CX_EXTERN CX_NONNULL CX_NODISCARD
363 CX_EXPORT void *cx_map_emplace(CxMap *map, CxHashKey key); 359 void *cx_map_emplace(CxMap *map, CxHashKey key);
364 360
365 /** 361 /**
366 * Allocates memory for a value in the map associated with the specified key. 362 * Allocates memory for a value in the map associated with the specified key.
367 * 363 *
368 * A possible existing value will be overwritten. 364 * A possible existing value will be overwritten.
391 * @param map the map 387 * @param map the map
392 * @param key the key 388 * @param key the key
393 * @return the value 389 * @return the value
394 * @see cxMapGet() 390 * @see cxMapGet()
395 */ 391 */
396 cx_attr_nonnull cx_attr_nodiscard 392 CX_EXTERN CX_NONNULL CX_NODISCARD
397 CX_EXPORT void *cx_map_get(const CxMap *map, CxHashKey key); 393 void *cx_map_get(const CxMap *map, CxHashKey key);
398 394
399 /** 395 /**
400 * Retrieves a value by using a key. 396 * Retrieves a value by using a key.
401 * 397 *
402 * If this map is storing pointers, the stored pointer is returned. 398 * If this map is storing pointers, the stored pointer is returned.
434 * @retval non-zero the key was not found 430 * @retval non-zero the key was not found
435 * 431 *
436 * @see cxMapRemove() 432 * @see cxMapRemove()
437 * @see cxMapRemoveAndGet() 433 * @see cxMapRemoveAndGet()
438 */ 434 */
439 cx_attr_nonnull_arg(1) 435 CX_EXTERN CX_NONNULL_ARG(1)
440 CX_EXPORT int cx_map_remove(CxMap *map, CxHashKey key, void *targetbuf); 436 int cx_map_remove(CxMap *map, CxHashKey key, void *targetbuf);
441 437
442 /** 438 /**
443 * Removes a key/value-pair from the map by using the key. 439 * Removes a key/value-pair from the map by using the key.
444 * 440 *
445 * Always invokes the destructor functions, if any, on the removed element. 441 * Always invokes the destructor functions, if any, on the removed element.
474 * @see cxMapRemove() 470 * @see cxMapRemove()
475 * @see CX_HASH_KEY() 471 * @see CX_HASH_KEY()
476 */ 472 */
477 #define cxMapRemoveAndGet(map, key, targetbuf) cx_map_remove(map, CX_HASH_KEY(key), targetbuf) 473 #define cxMapRemoveAndGet(map, key, targetbuf) cx_map_remove(map, CX_HASH_KEY(key), targetbuf)
478 474
479
480 /** 475 /**
481 * Performs a deep clone of one map into another. 476 * Performs a deep clone of one map into another.
482 * 477 *
483 * If the destination map already contains entries, the cloned entries 478 * If the destination map already contains entries, the cloned entries
484 * are added to that map, possibly overwriting existing elements when 479 * are added to that map, possibly overwriting existing elements when
497 * @param clone_allocator the allocator that is passed to the clone function 492 * @param clone_allocator the allocator that is passed to the clone function
498 * @param data optional additional data that is passed to the clone function 493 * @param data optional additional data that is passed to the clone function
499 * @retval zero when all elements were successfully cloned 494 * @retval zero when all elements were successfully cloned
500 * @retval non-zero when an allocation error occurred 495 * @retval non-zero when an allocation error occurred
501 */ 496 */
502 cx_attr_nonnull_arg(1, 2, 3) 497 CX_EXTERN CX_NONNULL_ARG(1, 2, 3)
503 CX_EXPORT int cxMapClone(CxMap *dst, const CxMap *src, 498 int cxMapClone(CxMap *dst, const CxMap *src,
504 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data); 499 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data);
505
506 500
507 /** 501 /**
508 * Clones entries of a map if their key is not present in another map. 502 * Clones entries of a map if their key is not present in another map.
509 * 503 *
510 * @param dst the destination map 504 * @param dst the destination map
514 * @param clone_allocator the allocator that is passed to the clone function 508 * @param clone_allocator the allocator that is passed to the clone function
515 * @param data optional additional data that is passed to the clone function 509 * @param data optional additional data that is passed to the clone function
516 * @retval zero when the elements were successfully cloned 510 * @retval zero when the elements were successfully cloned
517 * @retval non-zero when an allocation error occurred 511 * @retval non-zero when an allocation error occurred
518 */ 512 */
519 cx_attr_nonnull_arg(1, 2, 3, 4) 513 CX_EXTERN CX_NONNULL_ARG(1, 2, 3, 4)
520 CX_EXPORT int cxMapDifference(CxMap *dst, const CxMap *minuend, const CxMap *subtrahend, 514 int cxMapDifference(CxMap *dst, const CxMap *minuend, const CxMap *subtrahend,
521 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data); 515 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data);
522 516
523 /** 517 /**
524 * Clones entries of a map if their key is not present in a list. 518 * Clones entries of a map if their key is not present in a list.
525 * 519 *
535 * @param clone_allocator the allocator that is passed to the clone function 529 * @param clone_allocator the allocator that is passed to the clone function
536 * @param data optional additional data that is passed to the clone function 530 * @param data optional additional data that is passed to the clone function
537 * @retval zero when the elements were successfully cloned 531 * @retval zero when the elements were successfully cloned
538 * @retval non-zero when an allocation error occurred 532 * @retval non-zero when an allocation error occurred
539 */ 533 */
540 cx_attr_nonnull_arg(1, 2, 3, 4) 534 CX_EXTERN CX_NONNULL_ARG(1, 2, 3, 4)
541 CX_EXPORT int cxMapListDifference(CxMap *dst, const CxMap *src, const CxList *keys, 535 int cxMapListDifference(CxMap *dst, const CxMap *src, const CxList *keys,
542 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data); 536 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data);
543 537
544 538
545 /** 539 /**
546 * Clones entries of a map only if their key is present in another map. 540 * Clones entries of a map only if their key is present in another map.
552 * @param clone_allocator the allocator that is passed to the clone function 546 * @param clone_allocator the allocator that is passed to the clone function
553 * @param data optional additional data that is passed to the clone function 547 * @param data optional additional data that is passed to the clone function
554 * @retval zero when the elements were successfully cloned 548 * @retval zero when the elements were successfully cloned
555 * @retval non-zero when an allocation error occurred 549 * @retval non-zero when an allocation error occurred
556 */ 550 */
557 cx_attr_nonnull_arg(1, 2, 3, 4) 551 CX_EXTERN CX_NONNULL_ARG(1, 2, 3, 4)
558 CX_EXPORT int cxMapIntersection(CxMap *dst, const CxMap *src, const CxMap *other, 552 int cxMapIntersection(CxMap *dst, const CxMap *src, const CxMap *other,
559 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data); 553 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data);
560 554
561 /** 555 /**
562 * Clones entries of a map only if their key is present in a list. 556 * Clones entries of a map only if their key is present in a list.
563 * 557 *
573 * @param clone_allocator the allocator that is passed to the clone function 567 * @param clone_allocator the allocator that is passed to the clone function
574 * @param data optional additional data that is passed to the clone function 568 * @param data optional additional data that is passed to the clone function
575 * @retval zero when the elements were successfully cloned 569 * @retval zero when the elements were successfully cloned
576 * @retval non-zero when an allocation error occurred 570 * @retval non-zero when an allocation error occurred
577 */ 571 */
578 cx_attr_nonnull_arg(1, 2, 3, 4) 572 CX_EXTERN CX_NONNULL_ARG(1, 2, 3, 4)
579 CX_EXPORT int cxMapListIntersection(CxMap *dst, const CxMap *src, const CxList *keys, 573 int cxMapListIntersection(CxMap *dst, const CxMap *src, const CxList *keys,
580 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data); 574 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data);
581 575
582 /** 576 /**
583 * Clones entries into a map if their key does not exist yet. 577 * Clones entries into a map if their key does not exist yet.
584 * 578 *
593 * @param clone_allocator the allocator that is passed to the clone function 587 * @param clone_allocator the allocator that is passed to the clone function
594 * @param data optional additional data that is passed to the clone function 588 * @param data optional additional data that is passed to the clone function
595 * @retval zero when the elements were successfully cloned 589 * @retval zero when the elements were successfully cloned
596 * @retval non-zero when an allocation error occurred 590 * @retval non-zero when an allocation error occurred
597 */ 591 */
598 cx_attr_nonnull_arg(1, 2, 3) 592 CX_EXTERN CX_NONNULL_ARG(1, 2, 3)
599 CX_EXPORT int cxMapUnion(CxMap *dst, const CxMap *src, 593 int cxMapUnion(CxMap *dst, const CxMap *src,
600 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data); 594 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data);
601 595
602 /** 596 /**
603 * Performs a shallow clone of one map into another. 597 * Performs a shallow clone of one map into another.
604 * 598 *
620 * @param src the source map 614 * @param src the source map
621 * @retval zero when all elements were successfully cloned 615 * @retval zero when all elements were successfully cloned
622 * @retval non-zero when an allocation error occurred 616 * @retval non-zero when an allocation error occurred
623 * @see cxMapClone() 617 * @see cxMapClone()
624 */ 618 */
625 cx_attr_nonnull 619 CX_EXTERN CX_NONNULL
626 CX_EXPORT int cxMapCloneShallow(CxMap *dst, const CxMap *src); 620 int cxMapCloneShallow(CxMap *dst, const CxMap *src);
627 621
628 /** 622 /**
629 * Clones entries of a map if their key is not present in another map. 623 * Clones entries of a map if their key is not present in another map.
630 * 624 *
631 * This function uses the default allocator, if needed, and performs 625 * This function uses the default allocator, if needed, and performs
635 * @param minuend the map to subtract the entries from 629 * @param minuend the map to subtract the entries from
636 * @param subtrahend the map containing the elements to be subtracted 630 * @param subtrahend the map containing the elements to be subtracted
637 * @retval zero when the elements were successfully cloned 631 * @retval zero when the elements were successfully cloned
638 * @retval non-zero when an allocation error occurred 632 * @retval non-zero when an allocation error occurred
639 */ 633 */
640 cx_attr_nonnull 634 CX_EXTERN CX_NONNULL
641 CX_EXPORT int cxMapDifferenceShallow(CxMap *dst, const CxMap *minuend, const CxMap *subtrahend); 635 int cxMapDifferenceShallow(CxMap *dst, const CxMap *minuend, const CxMap *subtrahend);
642 636
643 /** 637 /**
644 * Clones entries of a map if their key is not present in a list. 638 * Clones entries of a map if their key is not present in a list.
645 * 639 *
646 * This function uses the default allocator, if needed, and performs 640 * This function uses the default allocator, if needed, and performs
656 * @param keys the list of @c CxKey items 650 * @param keys the list of @c CxKey items
657 * @retval zero when the elements were successfully cloned 651 * @retval zero when the elements were successfully cloned
658 * @retval non-zero when an allocation error occurred 652 * @retval non-zero when an allocation error occurred
659 * @see cxMapListDifference() 653 * @see cxMapListDifference()
660 */ 654 */
661 cx_attr_nonnull 655 CX_EXTERN CX_NONNULL
662 CX_EXPORT int cxMapListDifferenceShallow(CxMap *dst, const CxMap *src, const CxList *keys); 656 int cxMapListDifferenceShallow(CxMap *dst, const CxMap *src, const CxList *keys);
663
664 657
665 /** 658 /**
666 * Clones entries of a map only if their key is present in another map. 659 * Clones entries of a map only if their key is present in another map.
667 * 660 *
668 * This function uses the default allocator, if needed, and performs 661 * This function uses the default allocator, if needed, and performs
672 * @param src the map to clone the entries from 665 * @param src the map to clone the entries from
673 * @param other the map to check for existence of the keys 666 * @param other the map to check for existence of the keys
674 * @retval zero when the elements were successfully cloned 667 * @retval zero when the elements were successfully cloned
675 * @retval non-zero when an allocation error occurred 668 * @retval non-zero when an allocation error occurred
676 */ 669 */
677 cx_attr_nonnull 670 CX_EXTERN CX_NONNULL
678 CX_EXPORT int cxMapIntersectionShallow(CxMap *dst, const CxMap *src, const CxMap *other); 671 int cxMapIntersectionShallow(CxMap *dst, const CxMap *src, const CxMap *other);
679 672
680 /** 673 /**
681 * Clones entries of a map only if their key is present in a list. 674 * Clones entries of a map only if their key is present in a list.
682 * 675 *
683 * This function uses the default allocator, if needed, and performs 676 * This function uses the default allocator, if needed, and performs
692 * @param src the source map 685 * @param src the source map
693 * @param keys the list of @c CxKey items 686 * @param keys the list of @c CxKey items
694 * @retval zero when the elements were successfully cloned 687 * @retval zero when the elements were successfully cloned
695 * @retval non-zero when an allocation error occurred 688 * @retval non-zero when an allocation error occurred
696 */ 689 */
697 cx_attr_nonnull 690 CX_EXTERN CX_NONNULL
698 CX_EXPORT int cxMapListIntersectionShallow(CxMap *dst, const CxMap *src, const CxList *keys); 691 int cxMapListIntersectionShallow(CxMap *dst, const CxMap *src, const CxList *keys);
699 692
700 /** 693 /**
701 * Clones entries into a map if their key does not exist yet. 694 * Clones entries into a map if their key does not exist yet.
702 * 695 *
703 * This function uses the default allocator, if needed, and performs 696 * This function uses the default allocator, if needed, and performs
711 * @param dst the destination map 704 * @param dst the destination map
712 * @param src the map to clone the entries from 705 * @param src the map to clone the entries from
713 * @retval zero when the elements were successfully cloned 706 * @retval zero when the elements were successfully cloned
714 * @retval non-zero when an allocation error occurred 707 * @retval non-zero when an allocation error occurred
715 */ 708 */
716 cx_attr_nonnull 709 CX_EXTERN CX_NONNULL
717 CX_EXPORT int cxMapUnionShallow(CxMap *dst, const CxMap *src); 710 int cxMapUnionShallow(CxMap *dst, const CxMap *src);
718
719 711
720 /** 712 /**
721 * Compares the entries of two maps. 713 * Compares the entries of two maps.
722 * 714 *
723 * @param map the map 715 * @param map the map
727 * @retval negative when the first @p map has fewer keys than the @p other map 719 * @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 720 * @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 721 * @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 722 * of both maps is equal but a key or a value is different
731 */ 723 */
732 cx_attr_nonnull 724 CX_EXTERN CX_NONNULL
733 CX_EXPORT int cxMapCompare(const CxMap *map, const CxMap *other); 725 int cxMapCompare(const CxMap *map, const CxMap *other);
734
735 #ifdef __cplusplus
736 } // extern "C"
737 #endif
738 726
739 #endif // UCX_MAP_H 727 #endif // UCX_MAP_H

Mercurial Repository: ucx

mercurial