comparison: src/cx/array_list.h
src/cx/array_list.h
- changeset 1084
- 0bcd71d2615a
- parent 1066
- 8610f87a6b14
- child 1089
- 865c84fef6b4
equal
deleted
inserted
replaced
| 1083:cf54e413793c | 1084:0bcd71d2615a |
|---|---|
| 190 * Reserves memory for additional elements. | 190 * Reserves memory for additional elements. |
| 191 * | 191 * |
| 192 * This function checks if the \p capacity of the array is sufficient to hold | 192 * This function checks if the \p capacity of the array is sufficient to hold |
| 193 * at least \p size plus \p elem_count elements. If not, a reallocation is | 193 * at least \p size plus \p elem_count elements. If not, a reallocation is |
| 194 * performed with the specified \p reallocator. | 194 * performed with the specified \p reallocator. |
| 195 * You can create your own reallocator by hand or use the convenience function | |
| 196 * cx_array_reallocator(). | |
| 195 * | 197 * |
| 196 * This function can be useful to replace subsequent calls to cx_array_copy() | 198 * This function can be useful to replace subsequent calls to cx_array_copy() |
| 197 * with one single cx_array_reserve() and then - after guaranteeing a | 199 * with one single cx_array_reserve() and then - after guaranteeing a |
| 198 * sufficient capacity - use simple memmove() or memcpy(). | 200 * sufficient capacity - use simple memmove() or memcpy(). |
| 199 * | 201 * |
| 200 * The \p width refers to the size and capacity. Both must have the same width. | 202 * The \p width in bytes refers to the size and capacity. |
| 201 * Supported are 0, 8, 16, and 32, as well as 64 if running on a 64 bit | 203 * Both must have the same width. |
| 204 * Supported are 0, 1, 2, and 4, as well as 8 if running on a 64 bit | |
| 202 * architecture. If set to zero, the native word width is used. | 205 * architecture. If set to zero, the native word width is used. |
| 203 * | 206 * |
| 204 * @param array a pointer to the target array | 207 * @param array a pointer to the target array |
| 205 * @param size a pointer to the size of the array | 208 * @param size a pointer to the size of the array |
| 206 * @param capacity a pointer to the capacity of the array | 209 * @param capacity a pointer to the capacity of the array |
| 207 * @param width the width in bytes for the \p size and \p capacity or zero for default | 210 * @param width the width in bytes for the \p size and \p capacity or zero for default |
| 208 * @param elem_size the size of one element | 211 * @param elem_size the size of one element |
| 209 * @param elem_count the number of expected additional elements | 212 * @param elem_count the number of expected additional elements |
| 210 * @param reallocator the array reallocator to use | 213 * @param reallocator the array reallocator to use |
| 211 * @return zero on success, non-zero on failure | 214 * @return zero on success, non-zero on failure |
| 215 * @see cx_array_reallocator() | |
| 212 */ | 216 */ |
| 213 cx_attr_nonnull | 217 cx_attr_nonnull |
| 214 int cx_array_reserve( | 218 int cx_array_reserve( |
| 215 void **array, | 219 void **array, |
| 216 void *size, | 220 void *size, |
| 229 * the current array \p size. If the new index plus the number of elements added | 233 * the current array \p size. If the new index plus the number of elements added |
| 230 * would extend the array's size, the remaining \p capacity is used. | 234 * would extend the array's size, the remaining \p capacity is used. |
| 231 * | 235 * |
| 232 * If the \p capacity is also insufficient to hold the new data, a reallocation | 236 * If the \p capacity is also insufficient to hold the new data, a reallocation |
| 233 * attempt is made with the specified \p reallocator. | 237 * attempt is made with the specified \p reallocator. |
| 234 * | 238 * You can create your own reallocator by hand or use the convenience function |
| 235 * The \p width refers to the size and capacity. Both must have the same width. | 239 * cx_array_reallocator(). |
| 236 * Supported are 0, 8, 16, and 32, as well as 64 if running on a 64 bit | 240 * |
| 241 * The \p width in bytes refers to the size and capacity. | |
| 242 * Both must have the same width. | |
| 243 * Supported are 0, 1, 2, and 4, as well as 8 if running on a 64 bit | |
| 237 * architecture. If set to zero, the native word width is used. | 244 * architecture. If set to zero, the native word width is used. |
| 238 * | 245 * |
| 239 * @param target a pointer to the target array | 246 * @param target a pointer to the target array |
| 240 * @param size a pointer to the size of the target array | 247 * @param size a pointer to the size of the target array |
| 241 * @param capacity a pointer to the capacity of the target array | 248 * @param capacity a pointer to the capacity of the target array |
| 244 * @param src the source array | 251 * @param src the source array |
| 245 * @param elem_size the size of one element | 252 * @param elem_size the size of one element |
| 246 * @param elem_count the number of elements to copy | 253 * @param elem_count the number of elements to copy |
| 247 * @param reallocator the array reallocator to use | 254 * @param reallocator the array reallocator to use |
| 248 * @return zero on success, non-zero on failure | 255 * @return zero on success, non-zero on failure |
| 256 * @see cx_array_reallocator() | |
| 249 */ | 257 */ |
| 250 cx_attr_nonnull | 258 cx_attr_nonnull |
| 251 int cx_array_copy( | 259 int cx_array_copy( |
| 252 void **target, | 260 void **target, |
| 253 void *size, | 261 void *size, |
| 273 * @see CX_ARRAY_DECLARE() | 281 * @see CX_ARRAY_DECLARE() |
| 274 * @see cx_array_simple_copy() | 282 * @see cx_array_simple_copy() |
| 275 */ | 283 */ |
| 276 #define cx_array_simple_copy_a(reallocator, array, index, src, count) \ | 284 #define cx_array_simple_copy_a(reallocator, array, index, src, count) \ |
| 277 cx_array_copy((void**)&(array), &(array##_size), &(array##_capacity), \ | 285 cx_array_copy((void**)&(array), &(array##_size), &(array##_capacity), \ |
| 278 8*sizeof(array##_size), index, src, sizeof((array)[0]), count, \ | 286 sizeof(array##_size), index, src, sizeof((array)[0]), count, \ |
| 279 reallocator) | 287 reallocator) |
| 280 | 288 |
| 281 /** | 289 /** |
| 282 * Convenience macro that uses cx_array_copy() with a default layout and | 290 * Convenience macro that uses cx_array_copy() with a default layout and |
| 283 * the default reallocator. | 291 * the default reallocator. |
| 305 * @see CX_ARRAY_DECLARE() | 313 * @see CX_ARRAY_DECLARE() |
| 306 * @see cx_array_simple_reserve() | 314 * @see cx_array_simple_reserve() |
| 307 */ | 315 */ |
| 308 #define cx_array_simple_reserve_a(reallocator, array, count) \ | 316 #define cx_array_simple_reserve_a(reallocator, array, count) \ |
| 309 cx_array_reserve((void**)&(array), &(array##_size), &(array##_capacity), \ | 317 cx_array_reserve((void**)&(array), &(array##_size), &(array##_capacity), \ |
| 310 8*sizeof(array##_size), sizeof((array)[0]), count, \ | 318 sizeof(array##_size), sizeof((array)[0]), count, \ |
| 311 reallocator) | 319 reallocator) |
| 312 | 320 |
| 313 /** | 321 /** |
| 314 * Convenience macro that uses cx_array_reserve() with a default layout and | 322 * Convenience macro that uses cx_array_reserve() with a default layout and |
| 315 * the default reallocator. | 323 * the default reallocator. |
| 341 * @param elem a pointer to the element to add | 349 * @param elem a pointer to the element to add |
| 342 * @param reallocator the array reallocator to use | 350 * @param reallocator the array reallocator to use |
| 343 * @return zero on success, non-zero on failure | 351 * @return zero on success, non-zero on failure |
| 344 */ | 352 */ |
| 345 #define cx_array_add(target, size, capacity, elem_size, elem, reallocator) \ | 353 #define cx_array_add(target, size, capacity, elem_size, elem, reallocator) \ |
| 346 cx_array_copy((void**)(target), size, capacity, 8*sizeof(*(size)), \ | 354 cx_array_copy((void**)(target), size, capacity, sizeof(*(size)), \ |
| 347 *(size), elem, elem_size, 1, reallocator) | 355 *(size), elem, elem_size, 1, reallocator) |
| 348 | 356 |
| 349 /** | 357 /** |
| 350 * Convenience macro that uses cx_array_add() with a default layout and | 358 * Convenience macro that uses cx_array_add() with a default layout and |
| 351 * the specified reallocator. | 359 * the specified reallocator. |
