comparison: docs/Writerside/topics/list.h.md
docs/Writerside/topics/list.h.md
- changeset 1421
- 809eb30cd621
- parent 1420
- c6f55a2b3495
equal
deleted
inserted
replaced
| 1420:c6f55a2b3495 | 1421:809eb30cd621 |
|---|---|
| 162 | 162 |
| 163 When calling `cxListInsertSortedArray()` or `cxListInsertUniqueArray()`, the `array` must already be sorted. | 163 When calling `cxListInsertSortedArray()` or `cxListInsertUniqueArray()`, the `array` must already be sorted. |
| 164 | 164 |
| 165 The return values of the array-inserting functions are the number of elements that have been successfully _processed_. | 165 The return values of the array-inserting functions are the number of elements that have been successfully _processed_. |
| 166 Usually this is equivalent to the number of inserted elements, except for `cxListInsertUniqueArray()`, | 166 Usually this is equivalent to the number of inserted elements, except for `cxListInsertUniqueArray()`, |
| 167 where the actual number of inserted elements may be less than the number of successfully processed elements. | 167 where the actual number of inserted elements may be lower than the number of successfully processed elements. |
| 168 | 168 |
| 169 > Implementations are required to optimize the insertion of a sorted array into a sorted list in linear time, | 169 > Implementations are required to optimize the insertion of a sorted array into a sorted list in linear time, |
| 170 > while inserting each element separately via `cxListInsertSorted()` may take quadratic time. | 170 > while inserting each element separately via `cxListInsertSorted()` may take quadratic time. |
| 171 | 171 |
| 172 > The functions do not check if the list is already sorted, nor do they actively sort the list. | 172 > The functions do not check if the list is already sorted, nor do they actively sort the list. |
| 379 static cx_list_class my_list_class = { | 379 static cx_list_class my_list_class = { |
| 380 my_list_deallocate, | 380 my_list_deallocate, |
| 381 my_list_insert_element, | 381 my_list_insert_element, |
| 382 my_list_insert_array, | 382 my_list_insert_array, |
| 383 my_list_insert_sorted, | 383 my_list_insert_sorted, |
| 384 my_list_insert_unique, | |
| 384 my_list_insert_iter, | 385 my_list_insert_iter, |
| 385 my_list_remove, | 386 my_list_remove, |
| 386 my_list_clear, | 387 my_list_clear, |
| 387 my_list_swap, | 388 my_list_swap, |
| 388 my_list_at, | 389 my_list_at, |
| 425 |------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 426 |------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
| 426 | `clear` | Invoke destructor functions on all elements and remove them from the list. | | 427 | `clear` | Invoke destructor functions on all elements and remove them from the list. | |
| 427 | `deallocate` | Invoke destructor functions on all elements and deallocate the entire list memory. | | 428 | `deallocate` | Invoke destructor functions on all elements and deallocate the entire list memory. | |
| 428 | `insert_element` | Insert a single element at the specified index. Return a pointer to the allocated element or `NULL` on failure. | | 429 | `insert_element` | Insert a single element at the specified index. Return a pointer to the allocated element or `NULL` on failure. | |
| 429 | `insert_array` | Insert an array of elements starting at the specified index. Return the number of elements inserted. | | 430 | `insert_array` | Insert an array of elements starting at the specified index. Return the number of elements inserted. | |
| 430 | `insert_sorted` | Insert an array of sorted elements into a sorted list. Return the number of elements inserted. | | 431 | `insert_sorted` | Insert an array of sorted elements into a sorted list. Return the number of elements processed (equals the number of elements inserted in this case). | |
| 432 | `insert_unique` | Insert an array of sorted unique elements into a sorted list. Return the number of elements processed (not the number of elements inserted, which might be lower). | | |
| 431 | `insert_iter` | Insert a single element depending on the iterator position. The third argument to this function is zero when the element shall be inserted after the iterator position and non-zero if it shall be inserted before the iterator position. The implementation is also responsible for adjusting the iterator, respectively. | | 433 | `insert_iter` | Insert a single element depending on the iterator position. The third argument to this function is zero when the element shall be inserted after the iterator position and non-zero if it shall be inserted before the iterator position. The implementation is also responsible for adjusting the iterator, respectively. | |
| 432 | `remove` | Removes a multiple elements starting at the specified index. If a target buffer is specified, copy the elements to that buffer. Otherwise, invoke the destructor functions for the elements. Return the number of elements actually removed. | | 434 | `remove` | Removes a multiple elements starting at the specified index. If a target buffer is specified, copy the elements to that buffer. Otherwise, invoke the destructor functions for the elements. Return the number of elements actually removed. | |
| 433 | `swap` | Swap two elements by index. Return zero on success or non-zero when any index was out-of-bounds. | | 435 | `swap` | Swap two elements by index. Return zero on success or non-zero when any index was out-of-bounds. | |
| 434 | `at` | Return a pointer to the element at the specified index or `NULL` when the index is out-of-bounds. | | 436 | `at` | Return a pointer to the element at the specified index or `NULL` when the index is out-of-bounds. | |
| 435 | `find_remove` | Search for the specified element with the list's compare function and return the index if found. If the `remove` argument is true, invoke the destructor functions and remove the element. Return the list size if the element is not found. | | 437 | `find_remove` | Search for the specified element with the list's compare function and return the index if found. If the `remove` argument is true, invoke the destructor functions and remove the element. Return the list size if the element is not found. | |
| 452 | 454 |
| 453 | Default Function | Description | | 455 | Default Function | Description | |
| 454 |---------------------------------|-----------------------------------------------------------------------------------| | 456 |---------------------------------|-----------------------------------------------------------------------------------| |
| 455 | `cx_list_default_insert_array` | Falls back to multiple calls of `insert_element`. | | 457 | `cx_list_default_insert_array` | Falls back to multiple calls of `insert_element`. | |
| 456 | `cx_list_default_insert_sorted` | Uses linear search to find insertion points. | | 458 | `cx_list_default_insert_sorted` | Uses linear search to find insertion points. | |
| 459 | `cx_list_default_insert_unique` | Like `cx_default_insert_sorted` but skips elements that are already contained. | | |
| 457 | `cx_list_default_sort` | Copies all elements to an array, applies `qsort()`, and copies the elements back. | | 460 | `cx_list_default_sort` | Copies all elements to an array, applies `qsort()`, and copies the elements back. | |
| 458 | `cx_list_default_swap` | Uses a temporarily allocated buffer to perform a three-way-swap. | | 461 | `cx_list_default_swap` | Uses a temporarily allocated buffer to perform a three-way-swap. | |
| 459 | 462 |
| 460 | 463 |
| 461 <seealso> | 464 <seealso> |
