Mercurial > hg > ucx / file comparison

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

docs/Writerside/topics/array_list.h.md

changeset 1245
721e2032fa25
parent 1190
a7b913d5d589
equal deleted inserted replaced
1244:9a8e781258ac 1245:721e2032fa25
1 # Array List 1 # Array List
2 2
3 <warning> 3 Next to an array list implementation of the list interface,
4 Outdated Section - will be updated soon! 4 UCX offers several functions to work with plain C arrays equipped with a size and a capacity.
5 </warning> 5
6 6 The high level [list interface](list.h.md) is documented on a separate page and explains how lists are used
7 Since low-level array lists are just plain arrays, there is no need for such many low-level functions as for linked 7 that are created by one of the following functions.
8 lists. 8
9 However, there is one extremely powerful function that can be used for several complex tasks: `cx_array_copy`. 9 ```C
10 The full signature is shown below: 10 #include <cx/array_list.h>
11 ```c 11
12 CxList *cxArrayListCreate(const CxAllocator *allocator,
13 cx_compare_func comparator, size_t elem_size,
14 size_t initial_capacity);
15
16 CxList *cxArrayListCreateSimple(size_t elem_size,
17 size_t initial_capacity);
18 ```
19
20 The remaining documentation on this page concentrates on dealing with plain C arrays.
21
22 ## Declare Array with Size and Capacity
23
24 ```C
25 #include <cx/array_list.h>
26
27 #define CX_ARRAY_DECLARE_SIZED(type, name, size_type)
28
29 #define CX_ARRAY_DECLARE(type, name)
30
31 #define cx_array_initialize(ARRAY, capacity)
32
33 #define cx_array_initialize_a(allocator, ARRAY, capacity)
34 ```
35
36 <warning>
37 TODO: document
38 </warning>
39
40 ## Array Reallocator
41
42 ```C
43 #include <cx/array_list.h>
44
45 typedef struct {
46 void *(*realloc)(void *array, size_t capacity, size_t elem_size,
47 CxArrayReallocator *alloc);
48 void *ptr1;
49 void *ptr2;
50 size_t int1;
51 size_t int2;
52 } CxArrayReallocator;
53
54 CxArrayReallocator cx_array_reallocator(
55 const struct cx_allocator_s *allocator,
56 const void *stackmem
57 );
58 ```
59
60 <warning>
61 TODO: document
62 </warning>
63
64 ## Add Elements
65
66 ```C
67 #include <cx/array_list.h>
68
69 cx_array_add(target, size, capacity, elem_size, elem, reallocator)
70
71 #define cx_array_simple_add(ARRAY, elem)
72
73 #define cx_array_simple_add_a(reallocator, ARRAY, elem)
74 ```
75
76 <warning>
77 TODO: document
78 </warning>
79
80 ## Reserve
81
82 ```C
83 #include <cx/array_list.h>
84
85 int cx_array_reserve(
86 void **array, void *size, void *capacity, unsigned width,
87 size_t elem_size, size_t elem_count,
88 CxArrayReallocator *reallocator);
89
90 #define cx_array_simple_reserve(ARRAY, count)
91 #define cx_array_simple_reserve_a(reallocator, ARRAY, count)
92 ```
93
94 <warning>
95 TODO: document
96 </warning>
97
98 ## Copy
99
100 ```C
101 #include <cx/array_list.h>
102
12 int cx_array_copy( 103 int cx_array_copy(
13 void **target, 104 void **target, void *size, void *capacity, unsigned width,
14 void *size, 105 size_t index, const void *src,
15 void *capacity, 106 size_t elem_size, size_t elem_count,
16 unsigned width, 107 CxArrayReallocator *reallocator);
17 size_t index, 108
18 const void *src, 109 #define cx_array_simple_copy(ARRAY, index, src, count)
19 size_t elem_size, 110
20 size_t elem_count, 111 #define cx_array_simple_copy_a(reallocator, ARRAY, index, src, count)
21 struct cx_array_reallocator_s *reallocator 112 ```
22 ); 113
23 ``` 114 <warning>
115 TODO: outdated - rewrite
116 </warning>
117
24 The `target` argument is a pointer to the target array pointer. 118 The `target` argument is a pointer to the target array pointer.
25 The reason for this additional indirection is that this function writes 119 The reason for this additional indirection is that this function writes
26 back the pointer to the possibly reallocated array. 120 back the pointer to the possibly reallocated array.
27 The next two arguments are pointers to the `size` and `capacity` of the target array for which the width 121 The next two arguments are pointers to the `size` and `capacity` of the target array for which the width
28 (in bits) is specified in the `width` argument. 122 (in bits) is specified in the `width` argument.
37 position, `*target` points to - in this scenario, the need for reallocation must be avoided for obvious reasons 131 position, `*target` points to - in this scenario, the need for reallocation must be avoided for obvious reasons
38 * `index` does not need to be within size of the current array 132 * `index` does not need to be within size of the current array
39 * `index` does not even need to be within the capacity of the array 133 * `index` does not even need to be within the capacity of the array
40 * `width` must be one of 8, 16, 32, 64 (only on 64-bit systems), or zero (in which case the native word width is used) 134 * `width` must be one of 8, 16, 32, 64 (only on 64-bit systems), or zero (in which case the native word width is used)
41 135
42 If you just want to add one single element to an existing array, you can use the macro `cx_array_add()`. 136 ## Insertion Sort
43 You can use `CX_ARRAY_DECLARE()` to declare the necessary fields within a structure and then use the 137
44 `cx_array_simple_*()` convenience macros to reduce code overhead. 138 ```C
45 The convenience macros automatically determine the width of the size/capacity variables. 139 int cx_array_insert_sorted(
46 140 void **target, size_t *size, size_t *capacity,
47 <!-- 141 cx_compare_func cmp_func,
48 ## Undocumented Symbols (TODO) 142 const void *src, size_t elem_size, size_t elem_count,
49 ### cx_array_binary_search 143 CxArrayReallocator *reallocator);
50 ### cx_array_binary_search_inf 144
51 ### cx_array_binary_search_sup 145 #define cx_array_simple_insert_sorted(ARRAY,
52 ### cx_array_copy 146 src, elem_count, cmp_func)
53 ### cx_array_default_reallocator 147
54 ### cx_array_default_reallocator_impl 148 #define cx_array_simple_insert_sorted_a(reallocator, ARRAY,
55 ### cx_array_insert_sorted 149 src, elem_count, cmp_func)
56 ### cxArrayListCreate 150
57 ### cx_array_reallocator 151 int cx_array_add_sorted(
58 ### cx_array_reserve 152 void **target, size_t *size, size_t *capacity,
59 ### cx_array_swap 153 size_t elem_size, const void *elem,
60 ### cx_array_swap_sbo_size 154 cx_compare_func cmp_func,
61 --> 155 CxArrayReallocator *reallocator);
156
157 #define cx_array_simple_add_sorted(ARRAY,
158 elem, cmp_func)
159
160 #define cx_array_simple_add_sorted_a(reallocator, ARRAY,
161 elem, cmp_func)
162 ```
163
164 <warning>
165 TODO: document
166 </warning>
167
168 ## Binary Search
169
170 ```C
171 #include <cx/array_list.h>
172
173 size_t cx_array_binary_search(
174 const void *arr, size_t size, size_t elem_size,
175 const void *elem, cx_compare_func cmp_func);
176
177 size_t cx_array_binary_search_inf(
178 const void *arr, size_t size, size_t elem_size,
179 const void *elem, cx_compare_func cmp_func);
180
181 size_t cx_array_binary_search_sup(
182 const void *arr, size_t size, size_t elem_size,
183 const void *elem, cx_compare_func cmp_func);
184 ```
185
186 <warning>
187 TODO: document
188 </warning>
189
190 ## Iterators
191
192 ```C
193 #include <cx/iterator.h>
194
195 CxIterator cxIterator(const void *array,
196 size_t elem_size, size_t elem_count);
197
198 CxIterator cxMutIterator(void *array,
199 size_t elem_size, size_t elem_count, bool remove_keeps_order);
200
201 CxIterator cxIteratorPtr(const void *array, size_t elem_count);
202
203 CxIterator cxMutIteratorPtr(void *array, size_t elem_count,
204 bool remove_keeps_order);
205 ```
206
207 Iterators over plain C arrays are defined in [iterator.h](iterator.h.md#creating-an-iterator).
208
209 ## Other
210
211 ```C
212 #include <cx/array_list.h>
213
214 void cx_array_swap(
215 void *arr,
216 size_t elem_size,
217 size_t idx1,
218 size_t idx2
219 );
220 ```
221
222 <warning>
223 TODO: document
224 </warning>
225
62 <seealso> 226 <seealso>
63 <category ref="apidoc"> 227 <category ref="apidoc">
64 <a href="https://ucx.sourceforge.io/api/array__list_8h.html">array_list.h</a> 228 <a href="https://ucx.sourceforge.io/api/array__list_8h.html">array_list.h</a>
65 </category> 229 </category>
66 </seealso> 230 </seealso>

Mercurial Repository: ucx

mercurial