comparison: src/cx/list.h
src/cx/list.h
- changeset 1705
- 4df57f540e52
- parent 1675
- 36c0fb2b60b2
equal
deleted
inserted
replaced
| 1704:7bc94a96a621 | 1705:4df57f540e52 |
|---|---|
| 342 size_t cxListSize(const CxList *list); | 342 size_t cxListSize(const CxList *list); |
| 343 | 343 |
| 344 /** | 344 /** |
| 345 * Adds an item to the end of the list. | 345 * Adds an item to the end of the list. |
| 346 * | 346 * |
| 347 * If the list is not storing pointers and a @c NULL pointer is passed as the | |
| 348 * @c elem, this function returns non-zero and sets @c errno to EINVAL. | |
| 349 * | |
| 347 * @param list the list | 350 * @param list the list |
| 348 * @param elem a pointer to the element to add | 351 * @param elem a pointer to the element to add |
| 349 * @retval zero success | 352 * @retval zero success |
| 350 * @retval non-zero memory allocation failure | 353 * @retval non-zero memory allocation failure |
| 351 * @see cxListAddArray() | 354 * @see cxListAddArray() |
| 352 * @see cxListEmplace() | 355 * @see cxListEmplace() |
| 353 */ | 356 */ |
| 354 CX_EXTERN CX_NONNULL | 357 CX_EXTERN CX_NONNULL_ARG(1) |
| 355 int cxListAdd(CxList *list, const void *elem); | 358 int cxListAdd(CxList *list, const void *elem); |
| 356 | 359 |
| 357 /** | 360 /** |
| 358 * Adds multiple items to the end of the list. | 361 * Adds multiple items to the end of the list. |
| 359 * | 362 * |
| 376 | 379 |
| 377 /** | 380 /** |
| 378 * Inserts an item at the specified index. | 381 * Inserts an item at the specified index. |
| 379 * | 382 * |
| 380 * If the @p index equals the list @c size, this is effectively cxListAdd(). | 383 * If the @p index equals the list @c size, this is effectively cxListAdd(). |
| 384 * | |
| 385 * If the list is not storing pointers and a @c NULL pointer is passed as the | |
| 386 * @c elem, this function returns non-zero and sets @c errno to EINVAL. | |
| 381 * | 387 * |
| 382 * @param list the list | 388 * @param list the list |
| 383 * @param index the index the element shall have | 389 * @param index the index the element shall have |
| 384 * @param elem a pointer to the element to add | 390 * @param elem a pointer to the element to add |
| 385 * @retval zero success | 391 * @retval zero success |
| 386 * @retval non-zero memory allocation failure or the index is out of bounds | 392 * @retval non-zero memory allocation failure or the index is out of bounds |
| 387 * @see cxListInsertAfter() | 393 * @see cxListInsertAfter() |
| 388 * @see cxListInsertBefore() | 394 * @see cxListInsertBefore() |
| 389 * @see cxListEmplaceAt() | 395 * @see cxListEmplaceAt() |
| 390 */ | 396 */ |
| 391 CX_EXTERN CX_NONNULL | 397 CX_EXTERN CX_NONNULL_ARG(1) |
| 392 int cxListInsert(CxList *list, size_t index, const void *elem); | 398 int cxListInsert(CxList *list, size_t index, const void *elem); |
| 393 | 399 |
| 394 /** | 400 /** |
| 395 * Allocates memory for an element at the specified index and returns a pointer to that memory. | 401 * Allocates memory for an element at the specified index and returns a pointer to that memory. |
| 396 * | 402 * |
| 461 /** | 467 /** |
| 462 * Inserts an item into a sorted list. | 468 * Inserts an item into a sorted list. |
| 463 * | 469 * |
| 464 * If the list is not sorted already, the behavior is undefined. | 470 * If the list is not sorted already, the behavior is undefined. |
| 465 * | 471 * |
| 472 * If the list is not storing pointers and a @c NULL pointer is passed as the | |
| 473 * @c elem, this function returns non-zero and sets @c errno to EINVAL. | |
| 474 * | |
| 466 * @param list the list | 475 * @param list the list |
| 467 * @param elem a pointer to the element to add | 476 * @param elem a pointer to the element to add |
| 468 * @retval zero success | 477 * @retval zero success |
| 469 * @retval non-zero memory allocation failure | 478 * @retval non-zero memory allocation failure |
| 470 */ | 479 */ |
| 471 CX_EXTERN CX_NONNULL | 480 CX_EXTERN CX_NONNULL_ARG(1) |
| 472 int cxListInsertSorted(CxList *list, const void *elem); | 481 int cxListInsertSorted(CxList *list, const void *elem); |
| 473 | 482 |
| 474 /** | 483 /** |
| 475 * Inserts an item into a list if it does not exist. | 484 * Inserts an item into a list if it does not exist. |
| 476 * | 485 * |
| 477 * If the list is not sorted already, this function will check all elements | 486 * If the list is not sorted already, this function will check all elements |
| 478 * and append the new element when it was not found. | 487 * and append the new element when it was not found. |
| 479 * It is strongly recommended to use this function only on sorted lists, where | 488 * It is strongly recommended to use this function only on sorted lists, where |
| 480 * the element, if it is not contained, is inserted at the correct position. | 489 * the element, if it is not contained, is inserted at the correct position. |
| 481 * | 490 * |
| 491 * If the list is not storing pointers and a @c NULL pointer is passed as the | |
| 492 * @c elem, this function returns non-zero and sets @c errno to EINVAL. | |
| 493 * | |
| 482 * @param list the list | 494 * @param list the list |
| 483 * @param elem a pointer to the element to add | 495 * @param elem a pointer to the element to add |
| 484 * @retval zero success (also when the element was already in the list) | 496 * @retval zero success (also when the element was already in the list) |
| 485 * @retval non-zero memory allocation failure | 497 * @retval non-zero memory allocation failure |
| 486 */ | 498 */ |
| 487 CX_EXTERN CX_NONNULL | 499 CX_EXTERN CX_NONNULL_ARG(1) |
| 488 int cxListInsertUnique(CxList *list, const void *elem); | 500 int cxListInsertUnique(CxList *list, const void *elem); |
| 489 | 501 |
| 490 /** | 502 /** |
| 491 * Inserts multiple items to the list at the specified index. | 503 * Inserts multiple items to the list at the specified index. |
| 492 * If the @p index equals the list size, this is effectively cxListAddArray(). | 504 * If the @p index equals the list size, this is effectively cxListAddArray(). |
| 574 * be considered invalidated. | 586 * be considered invalidated. |
| 575 * | 587 * |
| 576 * If @p iter is not a list iterator, the behavior is undefined. | 588 * If @p iter is not a list iterator, the behavior is undefined. |
| 577 * If @p iter is a past-the-end iterator, the new element gets appended to the list. | 589 * If @p iter is a past-the-end iterator, the new element gets appended to the list. |
| 578 * | 590 * |
| 591 * If the list is not storing pointers and a @c NULL pointer is passed as the | |
| 592 * @c elem, this function returns non-zero and sets @c errno to EINVAL. | |
| 593 * | |
| 579 * @param iter an iterator | 594 * @param iter an iterator |
| 580 * @param elem the element to insert | 595 * @param elem the element to insert |
| 581 * @retval zero success | 596 * @retval zero success |
| 582 * @retval non-zero memory allocation failure | 597 * @retval non-zero memory allocation failure |
| 583 * @see cxListInsert() | 598 * @see cxListInsert() |
| 584 * @see cxListInsertBefore() | 599 * @see cxListInsertBefore() |
| 585 */ | 600 */ |
| 586 CX_EXTERN CX_NONNULL | 601 CX_EXTERN CX_NONNULL_ARG(1) |
| 587 int cxListInsertAfter(CxIterator *iter, const void *elem); | 602 int cxListInsertAfter(CxIterator *iter, const void *elem); |
| 588 | 603 |
| 589 /** | 604 /** |
| 590 * Inserts an element before the current location of the specified iterator. | 605 * Inserts an element before the current location of the specified iterator. |
| 591 * | 606 * |
| 592 * The used iterator remains operational, but all other active iterators should | 607 * The used iterator remains operational, but all other active iterators should |
| 593 * be considered invalidated. | 608 * be considered invalidated. |
| 594 * | 609 * |
| 595 * If @p iter is not a list iterator, the behavior is undefined. | 610 * If @p iter is not a list iterator, the behavior is undefined. |
| 596 * If @p iter is a past-the-end iterator, the new element gets appended to the list. | 611 * If @p iter is a past-the-end iterator, the new element gets appended to the list. |
| 612 * | |
| 613 * If the list is not storing pointers and a @c NULL pointer is passed as the | |
| 614 * @c elem, this function returns non-zero and sets @c errno to EINVAL. | |
| 597 * | 615 * |
| 598 * @param iter an iterator | 616 * @param iter an iterator |
| 599 * @param elem the element to insert | 617 * @param elem the element to insert |
| 600 * @retval zero success | 618 * @retval zero success |
| 601 * @retval non-zero memory allocation failure | 619 * @retval non-zero memory allocation failure |
| 602 * @see cxListInsert() | 620 * @see cxListInsert() |
| 603 * @see cxListInsertAfter() | 621 * @see cxListInsertAfter() |
| 604 */ | 622 */ |
| 605 CX_EXTERN CX_NONNULL | 623 CX_EXTERN CX_NONNULL_ARG(1) |
| 606 int cxListInsertBefore(CxIterator *iter, const void *elem); | 624 int cxListInsertBefore(CxIterator *iter, const void *elem); |
| 607 | 625 |
| 608 /** | 626 /** |
| 609 * Removes the element at the specified index. | 627 * Removes the element at the specified index. |
| 610 * | 628 * |
| 877 * @param elem the element to find | 895 * @param elem the element to find |
| 878 * @return the index of the element or the size of the list when the element is not found | 896 * @return the index of the element or the size of the list when the element is not found |
| 879 * @see cxListIndexValid() | 897 * @see cxListIndexValid() |
| 880 * @see cxListContains() | 898 * @see cxListContains() |
| 881 */ | 899 */ |
| 882 CX_EXTERN CX_NONNULL CX_NODISCARD | 900 CX_EXTERN CX_NONNULL_ARG(1) CX_NODISCARD |
| 883 size_t cxListFind(const CxList *list, const void *elem); | 901 size_t cxListFind(const CxList *list, const void *elem); |
| 884 | 902 |
| 885 /** | 903 /** |
| 886 * Checks if the list contains the specified element. | 904 * Checks if the list contains the specified element. |
| 887 * | 905 * |
| 891 * @param elem the element to find | 909 * @param elem the element to find |
| 892 * @retval true if the element is contained | 910 * @retval true if the element is contained |
| 893 * @retval false if the element is not contained | 911 * @retval false if the element is not contained |
| 894 * @see cxListFind() | 912 * @see cxListFind() |
| 895 */ | 913 */ |
| 896 CX_EXTERN CX_NONNULL CX_NODISCARD | 914 CX_EXTERN CX_NONNULL_ARG(1) CX_NODISCARD |
| 897 bool cxListContains(const CxList* list, const void* elem); | 915 bool cxListContains(const CxList* list, const void* elem); |
| 898 | 916 |
| 899 /** | 917 /** |
| 900 * Checks if the specified index is within bounds. | 918 * Checks if the specified index is within bounds. |
| 901 * | 919 * |
| 916 * @param elem the element to find and remove | 934 * @param elem the element to find and remove |
| 917 * @return the index of the now removed element or the list size | 935 * @return the index of the now removed element or the list size |
| 918 * when the element is not found or could not be removed | 936 * when the element is not found or could not be removed |
| 919 * @see cxListIndexValid() | 937 * @see cxListIndexValid() |
| 920 */ | 938 */ |
| 921 CX_EXTERN CX_NONNULL | 939 CX_EXTERN CX_NONNULL_ARG(1) |
| 922 size_t cxListFindRemove(CxList *list, const void *elem); | 940 size_t cxListFindRemove(CxList *list, const void *elem); |
| 923 | 941 |
| 924 /** | 942 /** |
| 925 * Sorts the list. | 943 * Sorts the list. |
| 926 * | 944 * |
