1.1 --- a/src/ucx/array.h Sat Aug 10 09:47:59 2019 +0200
1.2 +++ b/src/ucx/array.h Sat Aug 10 11:12:49 2019 +0200
1.3 @@ -131,18 +131,86 @@
1.4 void ucx_array_destroy(UcxArray *array);
1.5
1.6 /**
1.7 + * Inserts elements at the end of the array.
1.8 + *
1.9 + * This is an O(1) operation.
1.10 + * The array will automatically grow, if the capacity is exceeded.
1.11 + * If a pointer to data is provided, the data is copied into the array with
1.12 + * memcpy(). Otherwise the new elements are completely zeroed.
1.13 + *
1.14 + * @param array a pointer the array where to append the data
1.15 + * @param data a pointer to the data to insert (may be <code>NULL</code>)
1.16 + * @param count number of elements to copy from data (if data is
1.17 + * <code>NULL</code>, zeroed elements are appended)
1.18 + * @return zero on success, non-zero if a reallocation was necessary but failed
1.19 + * @see ucx_array_set_from()
1.20 + * @see ucx_array_append()
1.21 + */
1.22 +int ucx_array_append_from(UcxArray *array, void *data, size_t count);
1.23 +
1.24 +
1.25 +/**
1.26 + * Inserts elements at the beginning of the array.
1.27 + *
1.28 + * This is an expensive operation, because the contents must be moved.
1.29 + * If there is no particular reason to prepend data, you should use
1.30 + * ucx_array_append_from() instead.
1.31 + *
1.32 + * @param array a pointer the array where to prepend the data
1.33 + * @param data a pointer to the data to insert (may be <code>NULL</code>)
1.34 + * @param count number of elements to copy from data (if data is
1.35 + * <code>NULL</code>, zeroed elements are inserted)
1.36 + * @return zero on success, non-zero if a reallocation was necessary but failed
1.37 + * @see ucx_array_append_from()
1.38 + * @see ucx_array_set_from()
1.39 + * @see ucx_array_prepend()
1.40 + */
1.41 +int ucx_array_prepend_from(UcxArray *array, void *data, size_t count);
1.42 +
1.43 +
1.44 +/**
1.45 + * Sets elements starting at the specified index.
1.46 + *
1.47 + * If the any index is out of bounds, the array automatically grows.
1.48 + * The pointer to the data may be NULL, in which case the elements are zeroed.
1.49 + *
1.50 + * @param array a pointer the array where to set the data
1.51 + * @param index the index of the element to set
1.52 + * @param data a pointer to the data to insert (may be <code>NULL</code>)
1.53 + * @param count number of elements to copy from data (if data is
1.54 + * <code>NULL</code>, the memory in the array is zeroed)
1.55 + * @return zero on success, non-zero if a reallocation was necessary but failed
1.56 + * @see ucx_array_append_from()
1.57 + * @see ucx_array_set()
1.58 + */
1.59 +int ucx_array_set_from(UcxArray *array, size_t index, void *data, size_t count);
1.60 +
1.61 +/**
1.62 * Inserts an element at the end of the array.
1.63 *
1.64 * This is an O(1) operation.
1.65 * The array will automatically grow, if the capacity is exceeded.
1.66 - * If a pointer to data is provided, the data is copied into the array with
1.67 - * memcpy(). Otherwise the new element is completely zeroed.
1.68 + * If the type of the argument has a different size than the element size of
1.69 + * this array, the behavior is undefined.
1.70 *
1.71 * @param array a pointer the array where to append the data
1.72 - * @param data a pointer to the data to insert (may be <code>NULL</code>)
1.73 + * @param elem the value to insert
1.74 * @return zero on success, non-zero if a reallocation was necessary but failed
1.75 + * @see ucx_array_append_from()
1.76 + * @see ucx_array_set()
1.77 */
1.78 -int ucx_array_append(UcxArray *array, void *data);
1.79 +#define ucx_array_append(array, elem) ucx_array_appendv(array, elem)
1.80 +
1.81 +/**
1.82 + * For internal use.
1.83 + * Use ucx_array_append()
1.84 + *
1.85 + * @param array
1.86 + * @param ...
1.87 + * @return
1.88 + * @see ucx_array_append()
1.89 + */
1.90 +int ucx_array_appendv(UcxArray *array, ...);
1.91
1.92
1.93 /**
1.94 @@ -153,24 +221,51 @@
1.95 * ucx_array_append() instead.
1.96 *
1.97 * @param array a pointer the array where to prepend the data
1.98 - * @param data a pointer to the data to insert (may be <code>NULL</code>)
1.99 + * @param elem the value to insert
1.100 * @return zero on success, non-zero if a reallocation was necessary but failed
1.101 + * @see ucx_array_append()
1.102 + * @see ucx_array_set_from()
1.103 + * @see ucx_array_prepend_from()
1.104 */
1.105 -int ucx_array_prepend(UcxArray *array, void *data);
1.106 +#define ucx_array_prepend(array, elem) ucx_array_prependv(array, elem)
1.107 +
1.108 +/**
1.109 + * For internal use.
1.110 + * Use ucx_array_prepend()
1.111 + *
1.112 + * @param array
1.113 + * @param ...
1.114 + * @return
1.115 + * @see ucx_array_prepend()
1.116 + */
1.117 +int ucx_array_prependv(UcxArray *array, ...);
1.118
1.119
1.120 /**
1.121 * Sets an element at the specified index.
1.122 *
1.123 - * If the index is out of bounds, the array automatically grows.
1.124 - * The pointer to the data may be NULL, in which case the element is zeroed.
1.125 + * If the any index is out of bounds, the array automatically grows.
1.126 *
1.127 * @param array a pointer the array where to set the data
1.128 * @param index the index of the element to set
1.129 - * @param data a pointer to the data to insert (may be <code>NULL</code>)
1.130 + * @param elem the value to set
1.131 * @return zero on success, non-zero if a reallocation was necessary but failed
1.132 + * @see ucx_array_append()
1.133 + * @see ucx_array_set_from()
1.134 */
1.135 -int ucx_array_set(UcxArray *array, size_t index, void *data);
1.136 +#define ucx_array_set(array, index, elem) ucx_array_setv(array, index, elem)
1.137 +
1.138 +/**
1.139 + * For internal use.
1.140 + * Use ucx_array_set()
1.141 + *
1.142 + * @param array
1.143 + * @param index
1.144 + * @param ...
1.145 + * @return
1.146 + * @see ucx_array_set()
1.147 + */
1.148 +int ucx_array_setv(UcxArray *array, size_t index, ...);
1.149
1.150 /**
1.151 * Concatenates two arrays.
