comparison: src/ucx/array.h
src/ucx/array.h
- branch
- feature/array
- changeset 354
- 7fd13b9f8f60
- parent 353
- 135ce35d5108
- child 355
- d315a068235a
equal
deleted
inserted
replaced
| 353:135ce35d5108 | 354:7fd13b9f8f60 |
|---|---|
| 129 * @param array the array to destroy | 129 * @param array the array to destroy |
| 130 */ | 130 */ |
| 131 void ucx_array_destroy(UcxArray *array); | 131 void ucx_array_destroy(UcxArray *array); |
| 132 | 132 |
| 133 /** | 133 /** |
| 134 * Inserts an element at the end of the array. | 134 * Inserts elements at the end of the array. |
| 135 * | 135 * |
| 136 * This is an O(1) operation. | 136 * This is an O(1) operation. |
| 137 * The array will automatically grow, if the capacity is exceeded. | 137 * The array will automatically grow, if the capacity is exceeded. |
| 138 * If a pointer to data is provided, the data is copied into the array with | 138 * If a pointer to data is provided, the data is copied into the array with |
| 139 * memcpy(). Otherwise the new element is completely zeroed. | 139 * memcpy(). Otherwise the new elements are completely zeroed. |
| 140 * | 140 * |
| 141 * @param array a pointer the array where to append the data | 141 * @param array a pointer the array where to append the data |
| 142 * @param data a pointer to the data to insert (may be <code>NULL</code>) | 142 * @param data a pointer to the data to insert (may be <code>NULL</code>) |
| 143 * @return zero on success, non-zero if a reallocation was necessary but failed | 143 * @param count number of elements to copy from data (if data is |
| 144 */ | 144 * <code>NULL</code>, zeroed elements are appended) |
| 145 int ucx_array_append(UcxArray *array, void *data); | 145 * @return zero on success, non-zero if a reallocation was necessary but failed |
| 146 * @see ucx_array_set_from() | |
| 147 * @see ucx_array_append() | |
| 148 */ | |
| 149 int ucx_array_append_from(UcxArray *array, void *data, size_t count); | |
| 150 | |
| 151 | |
| 152 /** | |
| 153 * Inserts elements at the beginning of the array. | |
| 154 * | |
| 155 * This is an expensive operation, because the contents must be moved. | |
| 156 * If there is no particular reason to prepend data, you should use | |
| 157 * ucx_array_append_from() instead. | |
| 158 * | |
| 159 * @param array a pointer the array where to prepend the data | |
| 160 * @param data a pointer to the data to insert (may be <code>NULL</code>) | |
| 161 * @param count number of elements to copy from data (if data is | |
| 162 * <code>NULL</code>, zeroed elements are inserted) | |
| 163 * @return zero on success, non-zero if a reallocation was necessary but failed | |
| 164 * @see ucx_array_append_from() | |
| 165 * @see ucx_array_set_from() | |
| 166 * @see ucx_array_prepend() | |
| 167 */ | |
| 168 int ucx_array_prepend_from(UcxArray *array, void *data, size_t count); | |
| 169 | |
| 170 | |
| 171 /** | |
| 172 * Sets elements starting at the specified index. | |
| 173 * | |
| 174 * If the any index is out of bounds, the array automatically grows. | |
| 175 * The pointer to the data may be NULL, in which case the elements are zeroed. | |
| 176 * | |
| 177 * @param array a pointer the array where to set the data | |
| 178 * @param index the index of the element to set | |
| 179 * @param data a pointer to the data to insert (may be <code>NULL</code>) | |
| 180 * @param count number of elements to copy from data (if data is | |
| 181 * <code>NULL</code>, the memory in the array is zeroed) | |
| 182 * @return zero on success, non-zero if a reallocation was necessary but failed | |
| 183 * @see ucx_array_append_from() | |
| 184 * @see ucx_array_set() | |
| 185 */ | |
| 186 int ucx_array_set_from(UcxArray *array, size_t index, void *data, size_t count); | |
| 187 | |
| 188 /** | |
| 189 * Inserts an element at the end of the array. | |
| 190 * | |
| 191 * This is an O(1) operation. | |
| 192 * The array will automatically grow, if the capacity is exceeded. | |
| 193 * If the type of the argument has a different size than the element size of | |
| 194 * this array, the behavior is undefined. | |
| 195 * | |
| 196 * @param array a pointer the array where to append the data | |
| 197 * @param elem the value to insert | |
| 198 * @return zero on success, non-zero if a reallocation was necessary but failed | |
| 199 * @see ucx_array_append_from() | |
| 200 * @see ucx_array_set() | |
| 201 */ | |
| 202 #define ucx_array_append(array, elem) ucx_array_appendv(array, elem) | |
| 203 | |
| 204 /** | |
| 205 * For internal use. | |
| 206 * Use ucx_array_append() | |
| 207 * | |
| 208 * @param array | |
| 209 * @param ... | |
| 210 * @return | |
| 211 * @see ucx_array_append() | |
| 212 */ | |
| 213 int ucx_array_appendv(UcxArray *array, ...); | |
| 146 | 214 |
| 147 | 215 |
| 148 /** | 216 /** |
| 149 * Inserts an element at the beginning of the array. | 217 * Inserts an element at the beginning of the array. |
| 150 * | 218 * |
| 151 * This is an expensive operation, because the contents must be moved. | 219 * This is an expensive operation, because the contents must be moved. |
| 152 * If there is no particular reason to prepend data, you should use | 220 * If there is no particular reason to prepend data, you should use |
| 153 * ucx_array_append() instead. | 221 * ucx_array_append() instead. |
| 154 * | 222 * |
| 155 * @param array a pointer the array where to prepend the data | 223 * @param array a pointer the array where to prepend the data |
| 156 * @param data a pointer to the data to insert (may be <code>NULL</code>) | 224 * @param elem the value to insert |
| 157 * @return zero on success, non-zero if a reallocation was necessary but failed | 225 * @return zero on success, non-zero if a reallocation was necessary but failed |
| 158 */ | 226 * @see ucx_array_append() |
| 159 int ucx_array_prepend(UcxArray *array, void *data); | 227 * @see ucx_array_set_from() |
| 228 * @see ucx_array_prepend_from() | |
| 229 */ | |
| 230 #define ucx_array_prepend(array, elem) ucx_array_prependv(array, elem) | |
| 231 | |
| 232 /** | |
| 233 * For internal use. | |
| 234 * Use ucx_array_prepend() | |
| 235 * | |
| 236 * @param array | |
| 237 * @param ... | |
| 238 * @return | |
| 239 * @see ucx_array_prepend() | |
| 240 */ | |
| 241 int ucx_array_prependv(UcxArray *array, ...); | |
| 160 | 242 |
| 161 | 243 |
| 162 /** | 244 /** |
| 163 * Sets an element at the specified index. | 245 * Sets an element at the specified index. |
| 164 * | 246 * |
| 165 * If the index is out of bounds, the array automatically grows. | 247 * If the any index is out of bounds, the array automatically grows. |
| 166 * The pointer to the data may be NULL, in which case the element is zeroed. | |
| 167 * | 248 * |
| 168 * @param array a pointer the array where to set the data | 249 * @param array a pointer the array where to set the data |
| 169 * @param index the index of the element to set | 250 * @param index the index of the element to set |
| 170 * @param data a pointer to the data to insert (may be <code>NULL</code>) | 251 * @param elem the value to set |
| 171 * @return zero on success, non-zero if a reallocation was necessary but failed | 252 * @return zero on success, non-zero if a reallocation was necessary but failed |
| 172 */ | 253 * @see ucx_array_append() |
| 173 int ucx_array_set(UcxArray *array, size_t index, void *data); | 254 * @see ucx_array_set_from() |
| 255 */ | |
| 256 #define ucx_array_set(array, index, elem) ucx_array_setv(array, index, elem) | |
| 257 | |
| 258 /** | |
| 259 * For internal use. | |
| 260 * Use ucx_array_set() | |
| 261 * | |
| 262 * @param array | |
| 263 * @param index | |
| 264 * @param ... | |
| 265 * @return | |
| 266 * @see ucx_array_set() | |
| 267 */ | |
| 268 int ucx_array_setv(UcxArray *array, size_t index, ...); | |
| 174 | 269 |
| 175 /** | 270 /** |
| 176 * Concatenates two arrays. | 271 * Concatenates two arrays. |
| 177 * | 272 * |
| 178 * The contents of the second array are appended to the first array in one | 273 * The contents of the second array are appended to the first array in one |
