comparison: docs/Writerside/topics/list.h.md
docs/Writerside/topics/list.h.md
- changeset 1238
- 26299ce9c955
- parent 1237
- 5cba456aff67
equal
deleted
inserted
replaced
| 1237:5cba456aff67 | 1238:26299ce9c955 |
|---|---|
| 126 | 126 |
| 127 ```C | 127 ```C |
| 128 int cxListCompare(const CxList *list, const CxList *other); | 128 int cxListCompare(const CxList *list, const CxList *other); |
| 129 ``` | 129 ``` |
| 130 | 130 |
| 131 <warning> | 131 Arbitrary lists can be compared item-wise with `cxListCompare()`, as long as the compare functions of both lists are equivalent. |
| 132 TODO: add documentation | 132 |
| 133 </warning> | 133 That means, you can compare an UCX [array list](array_list.h.md) with a [linked list](linked_list.h.md), |
| 134 and you could even compare lists that are storing pointers with lists that are not storing pointers. | |
| 135 | |
| 136 However, the optimized list-internal compare implementation is only used, when both the compare functions and the list classes are identical. | |
| 137 Otherwise, `cxListCompare()` will behave as if you were iterating through both lists and manually comparing the items. | |
| 138 | |
| 139 The return value of `cxListCompare()` is zero, if the lists are item-wise equivalent. | |
| 140 If they are not, the non-zero return value equals the return value of the used compare function for the first pair of elements that are not equal. | |
| 134 | 141 |
| 135 ## Dispose | 142 ## Dispose |
| 136 | 143 |
| 137 ```C | 144 ```C |
| 138 void cxListFree(CxList *list); | 145 void cxListFree(CxList *list); |
| 139 ``` | 146 ``` |
| 140 | 147 |
| 141 <warning> | 148 No matter with which function a `CxList` has been created, you can _always_ deallocate the entire memory with a call to `cxListFree()`. |
| 142 TODO: add documentation | 149 |
| 143 </warning> | 150 The effect is equivalent to invoking `cxListClear()` plus deallocating the memory for the list structure. |
| 151 That means, for each item in the list, the destructor functions defined by `cxDefineDestructor()` or `cxDefineAdvancedDestructor()` are called, | |
| 152 before deallocating the list. | |
| 153 | |
| 154 When the list has been storing pointers, make sure that either another reference to the same memory exist in your program, | |
| 155 or any of the destructor functions deallocates the memory. | |
| 156 Otherwise, there is a risk of a memory leak. | |
| 144 | 157 |
| 145 ## Implement own List Structures | 158 ## Implement own List Structures |
| 146 | 159 |
| 147 <warning> | 160 <warning> |
| 148 TODO: add documentation | 161 TODO: add documentation |
