comparison: src/cx/array_list.h
src/cx/array_list.h
- changeset 986
- 38fa7e41194c
- parent 985
- 68754c7de906
equal
deleted
inserted
replaced
| 985:68754c7de906 | 986:38fa7e41194c |
|---|---|
| 151 const struct cx_allocator_s *allocator, | 151 const struct cx_allocator_s *allocator, |
| 152 const void *stackmem | 152 const void *stackmem |
| 153 ); | 153 ); |
| 154 | 154 |
| 155 /** | 155 /** |
| 156 * Return codes for array functions. | |
| 157 */ | |
| 158 enum cx_array_result { | |
| 159 CX_ARRAY_SUCCESS, | |
| 160 CX_ARRAY_REALLOC_NOT_SUPPORTED, | |
| 161 CX_ARRAY_REALLOC_FAILED, | |
| 162 }; | |
| 163 | |
| 164 /** | |
| 165 * Copies elements from one array to another. | 156 * Copies elements from one array to another. |
| 166 * | 157 * |
| 167 * The elements are copied to the \p target array at the specified \p index, | 158 * The elements are copied to the \p target array at the specified \p index, |
| 168 * overwriting possible elements. The \p index does not need to be in range of | 159 * overwriting possible elements. The \p index does not need to be in range of |
| 169 * the current array \p size. If the new index plus the number of elements added | 160 * the current array \p size. If the new index plus the number of elements added |
| 170 * would extend the array's size, and \p capacity is not \c NULL, the remaining | 161 * would extend the array's size, the remaining \p capacity is used. |
| 171 * capacity is used. | 162 * |
| 172 * | 163 * If the \p capacity is also insufficient to hold the new data, a reallocation |
| 173 * If the capacity is insufficient to hold the new data, a reallocation | 164 * attempt is made with the specified \p reallocator. |
| 174 * attempt is made, unless the \p reallocator is set to \c NULL, in which case | |
| 175 * this function ultimately returns a failure. | |
| 176 * | 165 * |
| 177 * @param target a pointer to the target array | 166 * @param target a pointer to the target array |
| 178 * @param size a pointer to the size of the target array | 167 * @param size a pointer to the size of the target array |
| 179 * @param capacity a pointer to the target array's capacity - | 168 * @param capacity a pointer to the capacity of the target array |
| 180 * \c NULL if only the size shall be used to bound the array (reallocations | |
| 181 * will NOT be supported in that case) | |
| 182 * @param index the index where the copied elements shall be placed | 169 * @param index the index where the copied elements shall be placed |
| 183 * @param src the source array | 170 * @param src the source array |
| 184 * @param elem_size the size of one element | 171 * @param elem_size the size of one element |
| 185 * @param elem_count the number of elements to copy | 172 * @param elem_count the number of elements to copy |
| 186 * @param reallocator the array reallocator to use, or \c NULL | 173 * @param reallocator the array reallocator to use |
| 187 * if reallocation shall not happen | 174 * @return zero on success, non-zero on failure |
| 188 * @return zero on success, non-zero error code on failure | 175 */ |
| 189 */ | 176 cx_attr_nonnull |
| 190 cx_attr_nonnull_arg(1, 2, 5) | 177 int cx_array_copy( |
| 191 enum cx_array_result cx_array_copy( | |
| 192 void **target, | 178 void **target, |
| 193 size_t *size, | 179 size_t *size, |
| 194 size_t *capacity, | 180 size_t *capacity, |
| 195 size_t index, | 181 size_t index, |
| 196 const void *src, | 182 const void *src, |
| 198 size_t elem_count, | 184 size_t elem_count, |
| 199 struct cx_array_reallocator_s *reallocator | 185 struct cx_array_reallocator_s *reallocator |
| 200 ); | 186 ); |
| 201 | 187 |
| 202 /** | 188 /** |
| 203 * Convenience macro that uses cx_array_copy() with a default layout and the default reallocator. | 189 * Convenience macro that uses cx_array_copy() with a default layout and |
| 190 * the default reallocator. | |
| 204 * | 191 * |
| 205 * @param array the name of the array (NOT a pointer to the array) | 192 * @param array the name of the array (NOT a pointer to the array) |
| 206 * @param index the index where the copied elements shall be placed | 193 * @param index the index where the copied elements shall be placed |
| 207 * @param src the source array | 194 * @param src the source array |
| 208 * @param count the number of elements to copy | 195 * @param count the number of elements to copy |
| 196 * @return zero on success, non-zero on failure | |
| 209 * @see CX_ARRAY_DECLARE() | 197 * @see CX_ARRAY_DECLARE() |
| 210 */ | 198 */ |
| 211 #define cx_array_simple_copy(array, index, src, count) \ | 199 #define cx_array_simple_copy(array, index, src, count) \ |
| 212 cx_array_copy((void**)&(array), &(array##_size), &(array##_capacity), \ | 200 cx_array_copy((void**)&(array), &(array##_size), &(array##_capacity), \ |
| 213 index, src, sizeof((array)[0]), count, cx_array_default_reallocator) | 201 index, src, sizeof((array)[0]), count, cx_array_default_reallocator) |
| 214 | 202 |
| 215 /** | 203 /** |
| 216 * Adds an element to an array with the possibility of allocating more space. | 204 * Adds an element to an array with the possibility of allocating more space. |
| 217 * | 205 * |
| 218 * The element \p elem is added to the end of the \p target array which containing | 206 * The element \p elem is added to the end of the \p target array which contains |
| 219 * \p size elements, already. The \p capacity must not be \c NULL and point a | 207 * \p size elements, already. The \p capacity must point to a variable denoting |
| 220 * variable holding the current maximum number of elements the array can hold. | 208 * the current maximum number of elements the array can hold. |
| 221 * | 209 * |
| 222 * If the capacity is insufficient to hold the new element, and the optional | 210 * If the capacity is insufficient to hold the new element, an attempt to |
| 223 * \p reallocator is not \c NULL, an attempt increase the \p capacity is made | 211 * increase the \p capacity is made and the new capacity is written back. |
| 224 * and the new capacity is written back. | |
| 225 * | 212 * |
| 226 * @param target a pointer to the target array | 213 * @param target a pointer to the target array |
| 227 * @param size a pointer to the size of the target array | 214 * @param size a pointer to the size of the target array |
| 228 * @param capacity a pointer to the target array's capacity - must not be \c NULL | 215 * @param capacity a pointer to the capacity of the target array |
| 229 * @param elem_size the size of one element | 216 * @param elem_size the size of one element |
| 230 * @param elem a pointer to the element to add | 217 * @param elem a pointer to the element to add |
| 231 * @param reallocator the array reallocator to use, or \c NULL if reallocation shall not happen | 218 * @param reallocator the array reallocator to use |
| 232 * @return zero on success, non-zero error code on failure | 219 * @return zero on success, non-zero on failure |
| 233 */ | 220 */ |
| 234 #define cx_array_add(target, size, capacity, elem_size, elem, reallocator) \ | 221 #define cx_array_add(target, size, capacity, elem_size, elem, reallocator) \ |
| 235 cx_array_copy((void**)(target), size, capacity, *(size), elem, elem_size, 1, reallocator) | 222 cx_array_copy((void**)(target), size, capacity, *(size), elem, elem_size, 1, reallocator) |
| 236 | 223 |
| 237 /** | 224 /** |
| 238 * Convenience macro that uses cx_array_add() with a default layout and | 225 * Convenience macro that uses cx_array_add() with a default layout and |
| 239 * the default reallocator. | 226 * the default reallocator. |
| 240 * | 227 * |
| 241 * @param array the name of the array (NOT a pointer to the array) | 228 * @param array the name of the array (NOT a pointer to the array) |
| 242 * @param elem the element to add (NOT a pointer, address is automatically taken) | 229 * @param elem the element to add (NOT a pointer, address is automatically taken) |
| 230 * @return zero on success, non-zero on failure | |
| 243 * @see CX_ARRAY_DECLARE() | 231 * @see CX_ARRAY_DECLARE() |
| 244 */ | 232 */ |
| 245 #define cx_array_simple_add(array, elem) \ | 233 #define cx_array_simple_add(array, elem) \ |
| 246 cx_array_simple_copy(array, array##_size, &(elem), 1) | 234 cx_array_simple_copy(array, array##_size, &(elem), 1) |
| 247 | 235 |
| 255 * If the capacity is insufficient to hold the new data, a reallocation | 243 * If the capacity is insufficient to hold the new data, a reallocation |
| 256 * attempt is made. | 244 * attempt is made. |
| 257 * | 245 * |
| 258 * @param target a pointer to the target array | 246 * @param target a pointer to the target array |
| 259 * @param size a pointer to the size of the target array | 247 * @param size a pointer to the size of the target array |
| 260 * @param capacity a pointer to the target array's capacity | 248 * @param capacity a pointer to the capacity of the target array |
| 261 * @param cmp_func the compare function for the elements | 249 * @param cmp_func the compare function for the elements |
| 262 * @param src the source array | 250 * @param src the source array |
| 263 * @param elem_size the size of one element | 251 * @param elem_size the size of one element |
| 264 * @param elem_count the number of elements to insert | 252 * @param elem_count the number of elements to insert |
| 265 * @param reallocator the array reallocator to use | 253 * @param reallocator the array reallocator to use |
| 266 * @return zero on success, non-zero error code on failure | 254 * @return zero on success, non-zero on failure |
| 267 */ | 255 */ |
| 268 cx_attr_nonnull | 256 cx_attr_nonnull |
| 269 enum cx_array_result cx_array_insert_sorted( | 257 int cx_array_insert_sorted( |
| 270 void **target, | 258 void **target, |
| 271 size_t *size, | 259 size_t *size, |
| 272 size_t *capacity, | 260 size_t *capacity, |
| 273 cx_compare_func cmp_func, | 261 cx_compare_func cmp_func, |
| 274 const void *src, | 262 const void *src, |
| 286 * If the capacity is insufficient to hold the new data, a reallocation | 274 * If the capacity is insufficient to hold the new data, a reallocation |
| 287 * attempt is made. | 275 * attempt is made. |
| 288 * | 276 * |
| 289 * @param target a pointer to the target array | 277 * @param target a pointer to the target array |
| 290 * @param size a pointer to the size of the target array | 278 * @param size a pointer to the size of the target array |
| 291 * @param capacity a pointer to the target array's capacity | 279 * @param capacity a pointer to the capacity of the target array |
| 292 * @param elem_size the size of one element | 280 * @param elem_size the size of one element |
| 293 * @param elem a pointer to the element to add | 281 * @param elem a pointer to the element to add |
| 294 * @param reallocator the array reallocator to use | 282 * @param reallocator the array reallocator to use |
| 295 * @return zero on success, non-zero error code on failure | 283 * @return zero on success, non-zero on failure |
| 296 */ | 284 */ |
| 297 #define cx_array_add_sorted(target, size, capacity, elem_size, elem, cmp_func, reallocator) \ | 285 #define cx_array_add_sorted(target, size, capacity, elem_size, elem, cmp_func, reallocator) \ |
| 298 cx_array_insert_sorted((void**)(target), size, capacity, cmp_func, elem, elem_size, 1, reallocator) | 286 cx_array_insert_sorted((void**)(target), size, capacity, cmp_func, elem, elem_size, 1, reallocator) |
| 299 | 287 |
| 300 /** | 288 /** |
| 302 * layout and the default reallocator. | 290 * layout and the default reallocator. |
| 303 * | 291 * |
| 304 * @param array the name of the array (NOT a pointer to the array) | 292 * @param array the name of the array (NOT a pointer to the array) |
| 305 * @param elem the element to add (NOT a pointer, address is automatically taken) | 293 * @param elem the element to add (NOT a pointer, address is automatically taken) |
| 306 * @param cmp_func the compare function for the elements | 294 * @param cmp_func the compare function for the elements |
| 295 * @return zero on success, non-zero on failure | |
| 307 * @see CX_ARRAY_DECLARE() | 296 * @see CX_ARRAY_DECLARE() |
| 308 */ | 297 */ |
| 309 #define cx_array_simple_add_sorted(array, elem, cmp_func) \ | 298 #define cx_array_simple_add_sorted(array, elem, cmp_func) \ |
| 310 cx_array_add_sorted(&array, &(array##_size), &(array##_capacity), \ | 299 cx_array_add_sorted(&array, &(array##_size), &(array##_capacity), \ |
| 311 sizeof((array)[0]), &(elem), cmp_func, cx_array_default_reallocator) | 300 sizeof((array)[0]), &(elem), cmp_func, cx_array_default_reallocator) |
| 316 * | 305 * |
| 317 * @param array the name of the array (NOT a pointer to the array) | 306 * @param array the name of the array (NOT a pointer to the array) |
| 318 * @param src pointer to the source array | 307 * @param src pointer to the source array |
| 319 * @param n number of elements in the source array | 308 * @param n number of elements in the source array |
| 320 * @param cmp_func the compare function for the elements | 309 * @param cmp_func the compare function for the elements |
| 310 * @return zero on success, non-zero on failure | |
| 321 * @see CX_ARRAY_DECLARE() | 311 * @see CX_ARRAY_DECLARE() |
| 322 */ | 312 */ |
| 323 #define cx_array_simple_insert_sorted(array, src, n, cmp_func) \ | 313 #define cx_array_simple_insert_sorted(array, src, n, cmp_func) \ |
| 324 cx_array_insert_sorted((void**)(&array), &(array##_size), &(array##_capacity), \ | 314 cx_array_insert_sorted((void**)(&array), &(array##_size), &(array##_capacity), \ |
| 325 cmp_func, src, sizeof((array)[0]), n, cx_array_default_reallocator) | 315 cmp_func, src, sizeof((array)[0]), n, cx_array_default_reallocator) |
