Mercurial > hg > ucx / file comparison

comparison: docs/Writerside/topics/list.h.md

docs/Writerside/topics/list.h.md

changeset 1237
5cba456aff67
parent 1236
f392f27a1dc6
equal deleted inserted replaced
1236:f392f27a1dc6 1237:5cba456aff67
6 6
7 The `list.h` header defines a common interface for all list implementations. 7 The `list.h` header defines a common interface for all list implementations.
8 8
9 UCX already comes with two common list implementations ([linked list](linked_list.h.md) and [array list](array_list.h.md)) 9 UCX already comes with two common list implementations ([linked list](linked_list.h.md) and [array list](array_list.h.md))
10 that should cover most use cases. 10 that should cover most use cases.
11 But if you feel the need to implement an own list, you will find instructions [below](#implementing-own-list-structures). 11 But if you feel the need to implement an own list, you will find instructions [below](#implement-own-list-structures).
12 12
13 ## Overview 13 ## Example
14
15 <warning>
16 TODO: add example how to work with lists
17 </warning>
18
19 > If you want to lazy-initialize lists, you can use the global `cxEmptyList` symbol as a placeholder instead of using a `NULL`-pointer.
20 > While you *must not* insert items into that list, you can safely access this list or create iterators.
21 > This allows you to write clean code without checking for `NULL`-pointer everywhere.
22 > You still need to make sure that the placeholder is replaced with an actual list before inserting items.
23
24 ## Insert
14 25
15 ```C 26 ```C
16 size_t cxListSize(const CxList *list);
17
18 int cxListAdd(CxList *list, const void *elem); 27 int cxListAdd(CxList *list, const void *elem);
19 28
20 size_t cxListAddArray(CxList *list, const void *array, size_t n); 29 size_t cxListAddArray(CxList *list, const void *array, size_t n);
21 30
22 int cxListInsert(CxList *list, size_t index, const void *elem); 31 int cxListInsert(CxList *list, size_t index, const void *elem);
30 const void *array, size_t n); 39 const void *array, size_t n);
31 40
32 int cxListInsertAfter(CxIterator *iter, const void *elem); 41 int cxListInsertAfter(CxIterator *iter, const void *elem);
33 42
34 int cxListInsertBefore(CxIterator *iter, const void *elem); 43 int cxListInsertBefore(CxIterator *iter, const void *elem);
44 ```
35 45
46 <warning>
47 TODO: add documentation
48 </warning>
49
50 ## Access and Find
51
52 ```C
53 size_t cxListSize(const CxList *list);
54
55 void *cxListAt(const CxList *list, size_t index);
56
57 size_t cxListFind(const CxList *list, const void *elem);
58
59 size_t cxListFindRemove(CxList *list, const void *elem);
60
61 bool cxListIndexValid(const CxList *list, size_t index);
62 ```
63
64 <warning>
65 TODO: add documentation
66 </warning>
67
68 ## Remove
69
70 ```C
36 int cxListRemove(CxList *list, size_t index); 71 int cxListRemove(CxList *list, size_t index);
37 72
38 int cxListRemoveAndGet(CxList *list, size_t index, void *targetbuf); 73 int cxListRemoveAndGet(CxList *list, size_t index, void *targetbuf);
39 74
40 size_t cxListRemoveArray(CxList *list, size_t index, size_t num); 75 size_t cxListRemoveArray(CxList *list, size_t index, size_t num);
41 76
42 size_t cxListRemoveArrayAndGet(CxList *list, size_t index, size_t num, 77 size_t cxListRemoveArrayAndGet(CxList *list, size_t index, size_t num,
43 void *targetbuf); 78 void *targetbuf);
44 79
45 void cxListClear(CxList *list); 80 void cxListClear(CxList *list);
81 ```
46 82
47 int cxListSwap(CxList *list, size_t i, size_t j); 83 <warning>
84 TODO: add documentation
85 </warning>
48 86
49 void *cxListAt(const CxList *list, size_t index); 87 ## Iterators
88
89 ```C
90 CxIterator cxListIterator(const CxList *list);
91
92 CxIterator cxListMutIterator(CxList *list);
93
94 CxIterator cxListBackwardsIterator(const CxList *list);
95
96 CxIterator cxListMutBackwardsIterator(CxList *list);
50 97
51 CxIterator cxListIteratorAt(const CxList *list, size_t index); 98 CxIterator cxListIteratorAt(const CxList *list, size_t index);
52 99
53 CxIterator cxListBackwardsIteratorAt(const CxList *list, size_t index); 100 CxIterator cxListBackwardsIteratorAt(const CxList *list, size_t index);
54 101
55 CxIterator cxListMutIteratorAt(CxList *list, size_t index); 102 CxIterator cxListMutIteratorAt(CxList *list, size_t index);
56 103
57 CxIterator cxListMutBackwardsIteratorAt(CxList *list, size_t index); 104 CxIterator cxListMutBackwardsIteratorAt(CxList *list, size_t index);
105 ```
58 106
59 CxIterator cxListIterator(const CxList *list); 107 <warning>
108 TODO: add documentation
109 </warning>
60 110
61 CxIterator cxListMutIterator(CxList *list); 111 ## Reorder
62 112
63 CxIterator cxListBackwardsIterator(const CxList *list); 113 ```C
64 114 int cxListSwap(CxList *list, size_t i, size_t j);
65 CxIterator cxListMutBackwardsIterator(CxList *list);
66
67 size_t cxListFind(const CxList *list, const void *elem);
68
69 bool cxListIndexValid(const CxList *list, size_t index);
70
71 size_t cxListFindRemove(CxList *list, const void *elem);
72 115
73 void cxListSort(CxList *list); 116 void cxListSort(CxList *list);
74 117
75 void cxListReverse(CxList *list); 118 void cxListReverse(CxList *list);
76
77 int cxListCompare(const CxList *list, const CxList *other);
78
79 void cxListFree(CxList *list);
80
81 extern CxList *const cxEmptyList;
82 ``` 119 ```
83 120
121 <warning>
122 TODO: add documentation
123 </warning>
84 124
85 ## Implementing own List Structures 125 ## Compare
126
127 ```C
128 int cxListCompare(const CxList *list, const CxList *other);
129 ```
130
131 <warning>
132 TODO: add documentation
133 </warning>
134
135 ## Dispose
136
137 ```C
138 void cxListFree(CxList *list);
139 ```
140
141 <warning>
142 TODO: add documentation
143 </warning>
144
145 ## Implement own List Structures
146
147 <warning>
148 TODO: add documentation
149 </warning>
86 150
87 <seealso> 151 <seealso>
88 <category ref="apidoc"> 152 <category ref="apidoc">
89 <a href="https://ucx.sourceforge.io/api/list_8h.html">list.h</a> 153 <a href="https://ucx.sourceforge.io/api/list_8h.html">list.h</a>
90 </category> 154 </category>

Mercurial Repository: ucx

mercurial