comparison: src/cx/array_list.h
src/cx/array_list.h
- changeset 831
- 7970eac1c598
- parent 819
- 5da2ead43077
- child 832
- 97df2e4c68fb
equal
deleted
inserted
replaced
| 830:c4dae6fe6d5b | 831:7970eac1c598 |
|---|---|
| 48 * The maximum item size in an array list that fits into stack buffer when swapped. | 48 * The maximum item size in an array list that fits into stack buffer when swapped. |
| 49 */ | 49 */ |
| 50 extern unsigned cx_array_swap_sbo_size; | 50 extern unsigned cx_array_swap_sbo_size; |
| 51 | 51 |
| 52 /** | 52 /** |
| 53 * Declares variables for an array that can be used with the convenience macros. | |
| 54 * | |
| 55 * @see cx_array_simple_add() | |
| 56 * @see cx_array_simple_copy() | |
| 57 */ | |
| 58 #define cx_array_declare(type, name) \ | |
| 59 type * name; \ | |
| 60 size_t name##_size; \ | |
| 61 size_t name##_capacity; | |
| 62 | |
| 63 /** | |
| 53 * Defines a reallocation mechanism for arrays. | 64 * Defines a reallocation mechanism for arrays. |
| 54 */ | 65 */ |
| 55 struct cx_array_reallocator_s { | 66 struct cx_array_reallocator_s { |
| 56 /** | 67 /** |
| 57 * Re-allocates space for the given array. | 68 * Reallocates space for the given array. |
| 58 * | 69 * |
| 59 * Implementations are not required to free the original array. | 70 * Implementations are not required to free the original array. |
| 60 * This allows re-allocation of static memory by allocating heap memory | 71 * This allows reallocation of static memory by allocating heap memory |
| 61 * and copying the array contents. The information in the custom fields of | 72 * and copying the array contents. The information in the custom fields of |
| 62 * the referenced allocator can be used to track the state of the memory | 73 * the referenced allocator can be used to track the state of the memory |
| 63 * or to transport other additional data. | 74 * or to transport other additional data. |
| 64 * | 75 * |
| 65 * @param array the array to reallocate | 76 * @param array the array to reallocate |
| 118 * | 129 * |
| 119 * If the capacity is insufficient to hold the new data, a reallocation | 130 * If the capacity is insufficient to hold the new data, a reallocation |
| 120 * attempt is made, unless the \p reallocator is set to \c NULL, in which case | 131 * attempt is made, unless the \p reallocator is set to \c NULL, in which case |
| 121 * this function ultimately returns a failure. | 132 * this function ultimately returns a failure. |
| 122 * | 133 * |
| 123 * @param target the target array | 134 * @param target a pointer to the target array |
| 124 * @param size a pointer to the size of the target array | 135 * @param size a pointer to the size of the target array |
| 125 * @param capacity a pointer to the target array's capacity - | 136 * @param capacity a pointer to the target array's capacity - |
| 126 * \c NULL if only the size shall be used to bound the array | 137 * \c NULL if only the size shall be used to bound the array |
| 127 * @param index the index where the copied elements shall be placed | 138 * @param index the index where the copied elements shall be placed |
| 128 * @param src the source array | 139 * @param src the source array |
| 129 * @param elem_size the size of one element | 140 * @param elem_size the size of one element |
| 130 * @param elem_count the number of elements to copy | 141 * @param elem_count the number of elements to copy |
| 131 * @param reallocator the array re-allocator to use, or \c NULL | 142 * @param reallocator the array reallocator to use, or \c NULL |
| 132 * if re-allocation shall not happen | 143 * if reallocation shall not happen |
| 133 * @return zero on success, non-zero error code on failure | 144 * @return zero on success, non-zero error code on failure |
| 134 */ | 145 */ |
| 135 enum cx_array_result cx_array_copy( | 146 enum cx_array_result cx_array_copy( |
| 136 void **target, | 147 void **target, |
| 137 size_t *size, | 148 size_t *size, |
| 142 size_t elem_count, | 153 size_t elem_count, |
| 143 struct cx_array_reallocator_s *reallocator | 154 struct cx_array_reallocator_s *reallocator |
| 144 ) __attribute__((__nonnull__(1, 2, 5))); | 155 ) __attribute__((__nonnull__(1, 2, 5))); |
| 145 | 156 |
| 146 /** | 157 /** |
| 158 * Convenience macro that uses cx_array_copy() with a default layout and the default reallocator. | |
| 159 * | |
| 160 * @param array the name of the array (NOT a pointer to the array) | |
| 161 * @param index the index where the copied elements shall be placed | |
| 162 * @param src the source array | |
| 163 * @param count the number of elements to copy | |
| 164 */ | |
| 165 #define cx_array_simple_copy(array, index, src, count) \ | |
| 166 cx_array_copy((void**)&(array), &(array##_size), &(array##_capacity), \ | |
| 167 index, src, sizeof((array)[0]), count, cx_array_default_reallocator) | |
| 168 | |
| 169 /** | |
| 147 * Adds an element to an array with the possibility of allocating more space. | 170 * Adds an element to an array with the possibility of allocating more space. |
| 148 * | 171 * |
| 149 * The element \p elem is added to the end of the \p target array which containing | 172 * The element \p elem is added to the end of the \p target array which containing |
| 150 * \p size elements, already. The \p capacity must not be \c NULL and point a | 173 * \p size elements, already. The \p capacity must not be \c NULL and point a |
| 151 * variable holding the current maximum number of elements the array can hold. | 174 * variable holding the current maximum number of elements the array can hold. |
| 152 * | 175 * |
| 153 * If the capacity is insufficient to hold the new element, and the optional | 176 * If the capacity is insufficient to hold the new element, and the optional |
| 154 * \p reallocator is not \c NULL, an attempt increase the \p capacity is made | 177 * \p reallocator is not \c NULL, an attempt increase the \p capacity is made |
| 155 * and the new capacity is written back. | 178 * and the new capacity is written back. |
| 156 * | 179 * |
| 157 * @param target the target array | 180 * @param target a pointer to the target array |
| 158 * @param size a pointer to the size of the target array | 181 * @param size a pointer to the size of the target array |
| 159 * @param capacity a pointer to the target array's capacity - must not be \c NULL | 182 * @param capacity a pointer to the target array's capacity - must not be \c NULL |
| 160 * @param elem_size the size of one element | 183 * @param elem_size the size of one element |
| 161 * @param elem the element to add | 184 * @param elem the element to add |
| 162 * @param reallocator the array re-allocator to use, or \c NULL | 185 * @param reallocator the array reallocator to use, or \c NULL if reallocation shall not happen |
| 163 * if re-allocation shall not happen | |
| 164 * @return zero on success, non-zero error code on failure | 186 * @return zero on success, non-zero error code on failure |
| 165 */ | 187 */ |
| 166 #define cx_array_add(target, size, capacity, elem_size, elem, reallocator) \ | 188 #define cx_array_add(target, size, capacity, elem_size, elem, reallocator) \ |
| 167 cx_array_copy((void**)(target), size, capacity, *(size), elem, elem_size, 1, reallocator) | 189 cx_array_copy((void**)(target), size, capacity, *(size), elem, elem_size, 1, reallocator) |
| 190 | |
| 191 /** | |
| 192 * Convenience macro that uses cx_array_add() with a default layout and the default reallocator. | |
| 193 * | |
| 194 * @param array the name of the array (NOT a pointer to the array) | |
| 195 * @param elem the element to add | |
| 196 */ | |
| 197 #define cx_array_simple_add(array, elem) \ | |
| 198 cx_array_simple_copy(array, array##_size, elem, 1) | |
| 168 | 199 |
| 169 /** | 200 /** |
| 170 * Swaps two array elements. | 201 * Swaps two array elements. |
| 171 * | 202 * |
| 172 * @param arr the array | 203 * @param arr the array |
