comparison: src/cx/array_list.h
src/cx/array_list.h
- changeset 1424
- 563033aa998c
- parent 1423
- 9a72258446cd
equal
deleted
inserted
replaced
| 1423:9a72258446cd | 1424:563033aa998c |
|---|---|
| 42 #ifdef __cplusplus | 42 #ifdef __cplusplus |
| 43 extern "C" { | 43 extern "C" { |
| 44 #endif | 44 #endif |
| 45 | 45 |
| 46 /** | 46 /** |
| 47 * The maximum item size in an array list that fits into stack buffer | 47 * The maximum item size in an array list that fits into |
| 48 * when swapped. | 48 * a stack buffer when swapped. |
| 49 */ | 49 */ |
| 50 cx_attr_export | 50 cx_attr_export |
| 51 extern const unsigned cx_array_swap_sbo_size; | 51 extern const unsigned cx_array_swap_sbo_size; |
| 52 | 52 |
| 53 /** | 53 /** |
| 82 /** Array capacity. */ size_type name##_capacity | 82 /** Array capacity. */ size_type name##_capacity |
| 83 | 83 |
| 84 /** | 84 /** |
| 85 * Declares variables for an array that can be used with the convenience macros. | 85 * Declares variables for an array that can be used with the convenience macros. |
| 86 * | 86 * |
| 87 * The size and capacity variables will have @c size_t type. | 87 * The size and capacity variables will have type @c size_t. |
| 88 * Use #CX_ARRAY_DECLARE_SIZED() to specify a different type. | 88 * Use #CX_ARRAY_DECLARE_SIZED() to specify a different type. |
| 89 * | 89 * |
| 90 * @par Examples | 90 * @par Examples |
| 91 * @code | 91 * @code |
| 92 * // int array | 92 * // int array |
| 145 * | 145 * |
| 146 * | 146 * |
| 147 * const CxAllocator *al = // ... | 147 * const CxAllocator *al = // ... |
| 148 * cx_array_initialize_a(al, myarray, 128); | 148 * cx_array_initialize_a(al, myarray, 128); |
| 149 * // ... | 149 * // ... |
| 150 * cxFree(al, myarray); // don't forget to free with same allocator | 150 * cxFree(al, myarray); // remember to free with the same allocator |
| 151 * @endcode | 151 * @endcode |
| 152 * | 152 * |
| 153 * @param allocator (@c CxAllocator*) the allocator | 153 * @param allocator (@c CxAllocator*) the allocator |
| 154 * @param array the name of the array | 154 * @param array the name of the array |
| 155 * @param capacity the initial capacity | 155 * @param capacity the initial capacity |
| 228 * Creates a new array reallocator. | 228 * Creates a new array reallocator. |
| 229 * | 229 * |
| 230 * When @p allocator is @c NULL, the cxDefaultAllocator will be used. | 230 * When @p allocator is @c NULL, the cxDefaultAllocator will be used. |
| 231 * | 231 * |
| 232 * When @p stackmem is not @c NULL, the reallocator is supposed to be used | 232 * When @p stackmem is not @c NULL, the reallocator is supposed to be used |
| 233 * @em only for the specific array that is initially located at @p stackmem. | 233 * @em only for the specific array initially located at @p stackmem. |
| 234 * When reallocation is needed, the reallocator checks, if the array is | 234 * When reallocation is needed, the reallocator checks if the array is |
| 235 * still located at @p stackmem and copies the contents to the heap. | 235 * still located at @p stackmem and copies the contents to the heap. |
| 236 * | 236 * |
| 237 * @note Invoking this function with both arguments @c NULL will return a | 237 * @note Invoking this function with both arguments being @c NULL will return a |
| 238 * reallocator that behaves like #cx_array_default_reallocator. | 238 * reallocator that behaves like #cx_array_default_reallocator. |
| 239 * | 239 * |
| 240 * @param allocator the allocator this reallocator shall be based on | 240 * @param allocator the allocator this reallocator shall be based on |
| 241 * @param stackmem the address of the array when the array is initially located | 241 * @param stackmem the address of the array when the array is initially located |
| 242 * on the stack or shall not reallocated in place | 242 * on the stack or shall not reallocate in place |
| 243 * @return an array reallocator | 243 * @return an array reallocator |
| 244 */ | 244 */ |
| 245 cx_attr_export | 245 cx_attr_export |
| 246 CxArrayReallocator cx_array_reallocator( | 246 CxArrayReallocator cx_array_reallocator( |
| 247 const struct cx_allocator_s *allocator, | 247 const struct cx_allocator_s *allocator, |
| 261 * with one single cx_array_reserve() and then - after guaranteeing a | 261 * with one single cx_array_reserve() and then - after guaranteeing a |
| 262 * sufficient capacity - use simple memmove() or memcpy(). | 262 * sufficient capacity - use simple memmove() or memcpy(). |
| 263 * | 263 * |
| 264 * The @p width in bytes refers to the size and capacity. | 264 * The @p width in bytes refers to the size and capacity. |
| 265 * Both must have the same width. | 265 * Both must have the same width. |
| 266 * Supported are 0, 1, 2, and 4, as well as 8 if running on a 64 bit | 266 * Supported are 0, 1, 2, and 4, as well as 8 if running on a 64-bit |
| 267 * architecture. If set to zero, the native word width is used. | 267 * architecture. If set to zero, the native word width is used. |
| 268 * | 268 * |
| 269 * @param array a pointer to the target array | 269 * @param array a pointer to the target array |
| 270 * @param size a pointer to the size of the array | 270 * @param size a pointer to the size of the array |
| 271 * @param capacity a pointer to the capacity of the array | 271 * @param capacity a pointer to the capacity of the array |
| 294 * Copies elements from one array to another. | 294 * Copies elements from one array to another. |
| 295 * | 295 * |
| 296 * The elements are copied to the @p target array at the specified @p index, | 296 * The elements are copied to the @p target array at the specified @p index, |
| 297 * overwriting possible elements. The @p index does not need to be in range of | 297 * overwriting possible elements. The @p index does not need to be in range of |
| 298 * the current array @p size. If the new index plus the number of elements added | 298 * the current array @p size. If the new index plus the number of elements added |
| 299 * would extend the array's size, the remaining @p capacity is used. | 299 * extends the array's size, the remaining @p capacity is used. |
| 300 * | 300 * |
| 301 * If the @p capacity is also insufficient to hold the new data, a reallocation | 301 * If the @p capacity is also insufficient to hold the new data, a reallocation |
| 302 * attempt is made with the specified @p reallocator. | 302 * attempt is made with the specified @p reallocator. |
| 303 * You can create your own reallocator by hand, use #cx_array_default_reallocator, | 303 * You can create your own reallocator by hand, use #cx_array_default_reallocator, |
| 304 * or use the convenience function cx_array_reallocator() to create a custom reallocator. | 304 * or use the convenience function cx_array_reallocator() to create a custom reallocator. |
| 305 * | 305 * |
| 306 * The @p width in bytes refers to the size and capacity. | 306 * The @p width in bytes refers to the size and capacity. |
| 307 * Both must have the same width. | 307 * Both must have the same width. |
| 308 * Supported are 0, 1, 2, and 4, as well as 8 if running on a 64 bit | 308 * Supported are 0, 1, 2, and 4, as well as 8 if running on a 64-bit |
| 309 * architecture. If set to zero, the native word width is used. | 309 * architecture. If set to zero, the native word width is used. |
| 310 * | 310 * |
| 311 * @param target a pointer to the target array | 311 * @param target a pointer to the target array |
| 312 * @param size a pointer to the size of the target array | 312 * @param size a pointer to the size of the target array |
| 313 * @param capacity a pointer to the capacity of the target array | 313 * @param capacity a pointer to the capacity of the target array |
| 808 /** | 808 /** |
| 809 * Swaps two array elements. | 809 * Swaps two array elements. |
| 810 * | 810 * |
| 811 * @param arr the array | 811 * @param arr the array |
| 812 * @param elem_size the element size | 812 * @param elem_size the element size |
| 813 * @param idx1 index of first element | 813 * @param idx1 index of the first element |
| 814 * @param idx2 index of second element | 814 * @param idx2 index of the second element |
| 815 */ | 815 */ |
| 816 cx_attr_nonnull | 816 cx_attr_nonnull |
| 817 cx_attr_export | 817 cx_attr_export |
| 818 void cx_array_swap( | 818 void cx_array_swap( |
| 819 void *arr, | 819 void *arr, |
| 824 | 824 |
| 825 /** | 825 /** |
| 826 * Allocates an array list for storing elements with @p elem_size bytes each. | 826 * Allocates an array list for storing elements with @p elem_size bytes each. |
| 827 * | 827 * |
| 828 * If @p elem_size is #CX_STORE_POINTERS, the created list stores pointers instead of | 828 * If @p elem_size is #CX_STORE_POINTERS, the created list stores pointers instead of |
| 829 * copies of the added elements and the compare function will be automatically set | 829 * copies of the added elements, and the compare function will be automatically set |
| 830 * to cx_cmp_ptr(), if none is given. | 830 * to cx_cmp_ptr(), if none is given. |
| 831 * | 831 * |
| 832 * @param allocator the allocator for allocating the list memory | 832 * @param allocator the allocator for allocating the list memory |
| 833 * (if @c NULL, the cxDefaultAllocator will be used) | 833 * (if @c NULL, the cxDefaultAllocator will be used) |
| 834 * @param comparator the comparator for the elements | 834 * @param comparator the comparator for the elements |
