comparison: src/cx/list.h
src/cx/list.h
- changeset 1428
- 0ac4aa1737fd
- parent 1426
- 3a89b31f0724
- child 1429
- 6e0c3a8a914a
equal
deleted
inserted
replaced
| 1427:943bfd9e7978 | 1428:0ac4aa1737fd |
|---|---|
| 419 */ | 419 */ |
| 420 cx_attr_nonnull | 420 cx_attr_nonnull |
| 421 CX_EXPORT int cxListInsertSorted(CxList *list, const void *elem); | 421 CX_EXPORT int cxListInsertSorted(CxList *list, const void *elem); |
| 422 | 422 |
| 423 /** | 423 /** |
| 424 * Inserts an item into a sorted list if it does not exist. | 424 * Inserts an item into a list if it does not exist. |
| 425 * | 425 * |
| 426 * If the list is not sorted already, the behavior is undefined. | 426 * If the list is not sorted already, this function will check all elements |
| 427 * and append the new element when it was not found. | |
| 428 * It is strongly recommended to use this function only on sorted lists, where | |
| 429 * the element, if it is not contained, is inserted at the correct position. | |
| 427 * | 430 * |
| 428 * @param list the list | 431 * @param list the list |
| 429 * @param elem a pointer to the element to add | 432 * @param elem a pointer to the element to add |
| 430 * @retval zero success (also when the element was already in the list) | 433 * @retval zero success (also when the element was already in the list) |
| 431 * @retval non-zero memory allocation failure | 434 * @retval non-zero memory allocation failure |
| 476 */ | 479 */ |
| 477 cx_attr_nonnull | 480 cx_attr_nonnull |
| 478 CX_EXPORT size_t cxListInsertSortedArray(CxList *list, const void *array, size_t n); | 481 CX_EXPORT size_t cxListInsertSortedArray(CxList *list, const void *array, size_t n); |
| 479 | 482 |
| 480 /** | 483 /** |
| 481 * Inserts a sorted array into a sorted list, skipping duplicates. | 484 * Inserts an array into a list, skipping duplicates. |
| 485 * | |
| 486 * The @p list does not need to be sorted (in contrast to cxListInsertSortedArray()). | |
| 487 * But it is strongly recommended to use this function only on sorted lists, | |
| 488 * because otherwise it will fall back to an inefficient algorithm which inserts | |
| 489 * all elements one by one. | |
| 490 * If the @p list is not sorted, the @p array also does not need to be sorted. | |
| 491 * But when the @p list is sorted, the @p array must also be sorted. | |
| 482 * | 492 * |
| 483 * This method is usually more efficient than inserting each element separately | 493 * This method is usually more efficient than inserting each element separately |
| 484 * because consecutive chunks of sorted data are inserted in one pass. | 494 * because consecutive chunks of sorted data are inserted in one pass. |
| 485 * | 495 * |
| 486 * If there is not enough memory to add all elements, the returned value is | 496 * If there is not enough memory to add all elements, the returned value is |
| 492 * inserted. That means, when no error occurred, the return value should | 502 * inserted. That means, when no error occurred, the return value should |
| 493 * be @p n. | 503 * be @p n. |
| 494 * | 504 * |
| 495 * If this list is storing pointers instead of objects @p array is expected to | 505 * If this list is storing pointers instead of objects @p array is expected to |
| 496 * be an array of pointers. | 506 * be an array of pointers. |
| 497 * | |
| 498 * If the list is not sorted already, the behavior is undefined. | |
| 499 * This is also the case when the @p array is not sorted. | |
| 500 * | 507 * |
| 501 * @param list the list | 508 * @param list the list |
| 502 * @param array a pointer to the elements to add | 509 * @param array a pointer to the elements to add |
| 503 * @param n the number of elements to add | 510 * @param n the number of elements to add |
| 504 * @return the number of added elements | 511 * @return the number of added elements |
