diff -r 135ce35d5108 -r 7fd13b9f8f60 src/ucx/array.h --- a/src/ucx/array.h Sat Aug 10 09:47:59 2019 +0200 +++ b/src/ucx/array.h Sat Aug 10 11:12:49 2019 +0200 @@ -131,18 +131,86 @@ void ucx_array_destroy(UcxArray *array); /** + * Inserts elements at the end of the array. + * + * This is an O(1) operation. + * The array will automatically grow, if the capacity is exceeded. + * If a pointer to data is provided, the data is copied into the array with + * memcpy(). Otherwise the new elements are completely zeroed. + * + * @param array a pointer the array where to append the data + * @param data a pointer to the data to insert (may be NULL) + * @param count number of elements to copy from data (if data is + * NULL, zeroed elements are appended) + * @return zero on success, non-zero if a reallocation was necessary but failed + * @see ucx_array_set_from() + * @see ucx_array_append() + */ +int ucx_array_append_from(UcxArray *array, void *data, size_t count); + + +/** + * Inserts elements at the beginning of the array. + * + * This is an expensive operation, because the contents must be moved. + * If there is no particular reason to prepend data, you should use + * ucx_array_append_from() instead. + * + * @param array a pointer the array where to prepend the data + * @param data a pointer to the data to insert (may be NULL) + * @param count number of elements to copy from data (if data is + * NULL, zeroed elements are inserted) + * @return zero on success, non-zero if a reallocation was necessary but failed + * @see ucx_array_append_from() + * @see ucx_array_set_from() + * @see ucx_array_prepend() + */ +int ucx_array_prepend_from(UcxArray *array, void *data, size_t count); + + +/** + * Sets elements starting at the specified index. + * + * If the any index is out of bounds, the array automatically grows. + * The pointer to the data may be NULL, in which case the elements are zeroed. + * + * @param array a pointer the array where to set the data + * @param index the index of the element to set + * @param data a pointer to the data to insert (may be NULL) + * @param count number of elements to copy from data (if data is + * NULL, the memory in the array is zeroed) + * @return zero on success, non-zero if a reallocation was necessary but failed + * @see ucx_array_append_from() + * @see ucx_array_set() + */ +int ucx_array_set_from(UcxArray *array, size_t index, void *data, size_t count); + +/** * Inserts an element at the end of the array. * * This is an O(1) operation. * The array will automatically grow, if the capacity is exceeded. - * If a pointer to data is provided, the data is copied into the array with - * memcpy(). Otherwise the new element is completely zeroed. + * If the type of the argument has a different size than the element size of + * this array, the behavior is undefined. * * @param array a pointer the array where to append the data - * @param data a pointer to the data to insert (may be NULL) + * @param elem the value to insert * @return zero on success, non-zero if a reallocation was necessary but failed + * @see ucx_array_append_from() + * @see ucx_array_set() */ -int ucx_array_append(UcxArray *array, void *data); +#define ucx_array_append(array, elem) ucx_array_appendv(array, elem) + +/** + * For internal use. + * Use ucx_array_append() + * + * @param array + * @param ... + * @return + * @see ucx_array_append() + */ +int ucx_array_appendv(UcxArray *array, ...); /** @@ -153,24 +221,51 @@ * ucx_array_append() instead. * * @param array a pointer the array where to prepend the data - * @param data a pointer to the data to insert (may be NULL) + * @param elem the value to insert * @return zero on success, non-zero if a reallocation was necessary but failed + * @see ucx_array_append() + * @see ucx_array_set_from() + * @see ucx_array_prepend_from() */ -int ucx_array_prepend(UcxArray *array, void *data); +#define ucx_array_prepend(array, elem) ucx_array_prependv(array, elem) + +/** + * For internal use. + * Use ucx_array_prepend() + * + * @param array + * @param ... + * @return + * @see ucx_array_prepend() + */ +int ucx_array_prependv(UcxArray *array, ...); /** * Sets an element at the specified index. * - * If the index is out of bounds, the array automatically grows. - * The pointer to the data may be NULL, in which case the element is zeroed. + * If the any index is out of bounds, the array automatically grows. * * @param array a pointer the array where to set the data * @param index the index of the element to set - * @param data a pointer to the data to insert (may be NULL) + * @param elem the value to set * @return zero on success, non-zero if a reallocation was necessary but failed + * @see ucx_array_append() + * @see ucx_array_set_from() */ -int ucx_array_set(UcxArray *array, size_t index, void *data); +#define ucx_array_set(array, index, elem) ucx_array_setv(array, index, elem) + +/** + * For internal use. + * Use ucx_array_set() + * + * @param array + * @param index + * @param ... + * @return + * @see ucx_array_set() + */ +int ucx_array_setv(UcxArray *array, size_t index, ...); /** * Concatenates two arrays.