ucx: comparison src/ucx/array.h

-:d315a068235a
+:77efe51c6c9a
 /**
 * Creates a new UCX array with the given capacity and element size.
 * @param capacity the initial capacity
 * @param elemsize the element size
-* @return a new UCX array structure
+* @return a pointer to a new UCX array structure
 */
-UcxArray ucx_array_new(size_t capacity, size_t elemsize);
+UcxArray* ucx_array_new(size_t capacity, size_t elemsize);
 /**
 * Creates a new UCX array using the specified allocator.
 *
 * @param capacity the initial capacity
 * @param elemsize the element size
 * @param allocator the allocator to use
-* @return a new UCX array structure
+* @return a pointer to new UCX array structure
 */
-UcxArray ucx_array_new_a(size_t capacity, size_t elemsize,
+UcxArray* ucx_array_new_a(size_t capacity, size_t elemsize,
 UcxAllocator* allocator);
 /**
+* Initializes a UCX array structure with the given capacity and element size.
+* The structure must be uninitialized as the data pointer will be overwritten.
+*
+* @param array the structure to initialize
+* @param capacity the initial capacity
+* @param elemsize the element size
+*/
+void ucx_array_init(UcxArray* array, size_t capacity, size_t elemsize);
+/**
+* Initializes a UCX array structure using the specified allocator.
+* The structure must be uninitialized as the data pointer will be overwritten.
+*
+* @param capacity the initial capacity
+* @param elemsize the element size
+* @param allocator the allocator to use
+*/
+void ucx_array_init_a(UcxArray* array, size_t capacity, size_t elemsize,
+UcxAllocator* allocator);
+/**
 * Creates an shallow copy of an array.
 *
 * This function clones the specified array by using memcpy().
-*
+* If the destination capacity is insufficient, an automatic reallocation is
-* @param array the array to copy
+* attempted.
-* @return the copy (may be an empty array on allocation errors)
+*
-*/
+* @param dest the array to copy to
-UcxArray ucx_array_clone(UcxArray array);
+* @param src the array to copy from
+* @return zero on success, non-zero on reallocation failure.
+*/
+int ucx_array_clone(UcxArray* dest, UcxArray const* src);
 /**
 * Compares two UCX arrays element-wise by using a compare function.
 *
 * @param array2 the second array
 * @param cmpfnc the compare function
 * @param data additional data for the compare function
 * @return 1, if and only if the two arrays equal element-wise, 0 otherwise
 */
-int ucx_array_equals(UcxArray array1, UcxArray array2,
+int ucx_array_equals(UcxArray const *array1, UcxArray const *array2,
 cmp_func cmpfnc, void* data);
 /**
 * Destroys the array.
 *
 * freed separately.
 *
 * @param array the array to destroy
 */
 void ucx_array_destroy(UcxArray *array);
+/**
+* Destroys and frees the array.
+*
+* @param array the array to free
+*/
+void ucx_array_free(UcxArray *array);
 /**
 * Inserts elements at the end of the array.
 *
 * This is an O(1) operation.
 * @param array the array to retrieve the element from
 * @param index index of the element to return
 * @return a pointer to the element at the specified index or <code>NULL</code>,
 * if the index is greater than the array size
 */
-void *ucx_array_at(UcxArray array, size_t index);
+void *ucx_array_at(UcxArray const* array, size_t index);
 /**
 * Returns the index of an element containing the specified data.
 *
 * This function uses a cmp_func() to compare the data of each list element
 * @param cmpfnc the compare function
 * @param data additional data for the compare function
 * @return the index of the element containing the specified data or the size of
 * the array, if the data is not found in this array
 */
-size_t ucx_array_find(UcxArray array, void *elem, cmp_func cmpfnc, void *data);
+size_t ucx_array_find(UcxArray const *array, void *elem,
+cmp_func cmpfnc, void *data);
 /**
 * Checks, if an array contains a specific element.
 *
 * An element is found, if ucx_array_find() returns a value less than the size.
 * @param cmpfnc the compare function
 * @param data additional data for the compare function
 * @return 1, if and only if the array contains the specified element data
 * @see ucx_array_find()
 */
-int ucx_array_contains(UcxArray array, void *elem, cmp_func cmpfnc, void *data);
+int ucx_array_contains(UcxArray const *array, void *elem,
+cmp_func cmpfnc, void *data);
 /**
 * Sorts a UcxArray with the best available sort algorithm.
 *
 * The qsort_r() function is used, if available (glibc, FreeBSD or MacOS).
 *
 * @param array the array to sort
 * @param cmpfnc the function that shall be used to compare the element data
 * @param data additional data for the cmp_func() or <code>NULL</code>
 */
-void ucx_array_sort(UcxArray array, cmp_func cmpfnc, void *data);
+void ucx_array_sort(UcxArray* array, cmp_func cmpfnc, void *data);
 /**
 * Removes an element from the array.
 *
 * This is in general an expensive operation, because several elements may

Mercurial > hg > ucx / file comparison

comparison: src/ucx/array.h

src/ucx/array.h