--- a/ucx/cx/list.h Thu Nov 28 17:53:13 2024 +0100
+++ b/ucx/cx/list.h Mon Jan 06 21:18:36 2025 +0100
@@ -26,11 +26,11 @@
* POSSIBILITY OF SUCH DAMAGE.
*/
/**
- * \file list.h
- * \brief Interface for list implementations.
- * \author Mike Becker
- * \author Olaf Wintermann
- * \copyright 2-Clause BSD License
+ * @file list.h
+ * @brief Interface for list implementations.
+ * @author Mike Becker
+ * @author Olaf Wintermann
+ * @copyright 2-Clause BSD License
*/
#ifndef UCX_LIST_H
@@ -52,15 +52,18 @@
* Structure for holding the base data of a list.
*/
struct cx_list_s {
+ /**
+ * Common members for collections.
+ */
CX_COLLECTION_BASE;
/**
* The list class definition.
*/
- cx_list_class const *cl;
+ const cx_list_class *cl;
/**
* The actual implementation in case the list class is delegating.
*/
- cx_list_class const *climpl;
+ const cx_list_class *climpl;
};
/**
@@ -71,9 +74,9 @@
* Destructor function.
*
* Implementations SHALL invoke the content destructor functions if provided
- * and SHALL deallocate the list memory, if an allocator is provided.
+ * and SHALL deallocate the entire list memory.
*/
- void (*destructor)(struct cx_list_s *list);
+ void (*deallocate)(struct cx_list_s *list);
/**
* Member function for inserting a single element.
@@ -82,17 +85,30 @@
int (*insert_element)(
struct cx_list_s *list,
size_t index,
- void const *data
+ const void *data
);
/**
* Member function for inserting multiple elements.
* Implementors SHOULD see to performant implementations for corner cases.
+ *
+ * @see cx_list_default_insert_array()
*/
size_t (*insert_array)(
struct cx_list_s *list,
size_t index,
- void const *data,
+ const void *data,
+ size_t n
+ );
+
+ /**
+ * Member function for inserting sorted elements into a sorted list.
+ *
+ * @see cx_list_default_insert_sorted()
+ */
+ size_t (*insert_sorted)(
+ struct cx_list_s *list,
+ const void *sorted_data,
size_t n
);
@@ -101,16 +117,25 @@
*/
int (*insert_iter)(
struct cx_iterator_s *iter,
- void const *elem,
+ const void *elem,
int prepend
);
/**
- * Member function for removing an element.
+ * Member function for removing elements.
+ *
+ * Implementations SHALL check if @p targetbuf is set and copy the elements
+ * to the buffer without invoking any destructor.
+ * When @p targetbuf is not set, the destructors SHALL be invoked.
+ *
+ * The function SHALL return the actual number of elements removed, which
+ * might be lower than @p num when going out of bounds.
*/
- int (*remove)(
+ size_t (*remove)(
struct cx_list_s *list,
- size_t index
+ size_t index,
+ size_t num,
+ void *targetbuf
);
/**
@@ -120,6 +145,8 @@
/**
* Member function for swapping two elements.
+ *
+ * @see cx_list_default_swap()
*/
int (*swap)(
struct cx_list_s *list,
@@ -131,7 +158,7 @@
* Member function for element lookup.
*/
void *(*at)(
- struct cx_list_s const *list,
+ const struct cx_list_s *list,
size_t index
);
@@ -140,21 +167,26 @@
*/
ssize_t (*find_remove)(
struct cx_list_s *list,
- void const *elem,
+ const void *elem,
bool remove
);
/**
- * Member function for sorting the list in-place.
+ * Member function for sorting the list.
+ *
+ * @see cx_list_default_sort()
*/
void (*sort)(struct cx_list_s *list);
/**
- * Member function for comparing this list to another list of the same type.
+ * Optional member function for comparing this list
+ * to another list of the same type.
+ * If set to @c NULL, comparison won't be optimized.
*/
+ cx_attr_nonnull
int (*compare)(
- struct cx_list_s const *list,
- struct cx_list_s const *other
+ const struct cx_list_s *list,
+ const struct cx_list_s *other
);
/**
@@ -166,13 +198,88 @@
* Member function for returning an iterator pointing to the specified index.
*/
struct cx_iterator_s (*iterator)(
- struct cx_list_s const *list,
+ const struct cx_list_s *list,
size_t index,
bool backward
);
};
/**
+ * Default implementation of an array insert.
+ *
+ * This function uses the element insert function for each element of the array.
+ *
+ * Use this in your own list class if you do not want to implement an optimized
+ * version for your list.
+ *
+ * @param list the list
+ * @param index the index where to insert the data
+ * @param data a pointer to the array of data to insert
+ * @param n the number of elements to insert
+ * @return the number of elements actually inserted
+ */
+cx_attr_nonnull
+size_t cx_list_default_insert_array(
+ struct cx_list_s *list,
+ size_t index,
+ const void *data,
+ size_t n
+);
+
+/**
+ * Default implementation of a sorted insert.
+ *
+ * This function uses the array insert function to insert consecutive groups
+ * of sorted data.
+ *
+ * The source data @em must already be sorted wrt. the list's compare function.
+ *
+ * Use this in your own list class if you do not want to implement an optimized
+ * version for your list.
+ *
+ * @param list the list
+ * @param sorted_data a pointer to the array of pre-sorted data to insert
+ * @param n the number of elements to insert
+ * @return the number of elements actually inserted
+ */
+cx_attr_nonnull
+size_t cx_list_default_insert_sorted(
+ struct cx_list_s *list,
+ const void *sorted_data,
+ size_t n
+);
+
+/**
+ * Default unoptimized sort implementation.
+ *
+ * This function will copy all data to an array, sort the array with standard
+ * qsort, and then copy the data back to the list memory.
+ *
+ * Use this in your own list class if you do not want to implement an optimized
+ * version for your list.
+ *
+ * @param list the list that shall be sorted
+ */
+cx_attr_nonnull
+void cx_list_default_sort(struct cx_list_s *list);
+
+/**
+ * Default unoptimized swap implementation.
+ *
+ * Use this in your own list class if you do not want to implement an optimized
+ * version for your list.
+ *
+ * @param list the list in which to swap
+ * @param i index of one element
+ * @param j index of the other element
+ * @retval zero success
+ * @retval non-zero when indices are out of bounds or memory
+ * allocation for the temporary buffer fails
+ */
+cx_attr_nonnull
+int cx_list_default_swap(struct cx_list_s *list, size_t i, size_t j);
+
+/**
* Common type for all list implementations.
*/
typedef struct cx_list_s CxList;
@@ -186,7 +293,7 @@
* @param list the list
* @see cxListStorePointers()
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
void cxListStoreObjects(CxList *list);
/**
@@ -201,7 +308,7 @@
* @param list the list
* @see cxListStoreObjects()
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
void cxListStorePointers(CxList *list);
/**
@@ -211,8 +318,8 @@
* @return true, if this list is storing pointers
* @see cxListStorePointers()
*/
-__attribute__((__nonnull__))
-static inline bool cxListIsStoringPointers(CxList const *list) {
+cx_attr_nonnull
+static inline bool cxListIsStoringPointers(const CxList *list) {
return list->collection.store_pointer;
}
@@ -222,8 +329,8 @@
* @param list the list
* @return the number of currently stored elements
*/
-__attribute__((__nonnull__))
-static inline size_t cxListSize(CxList const *list) {
+cx_attr_nonnull
+static inline size_t cxListSize(const CxList *list) {
return list->collection.size;
}
@@ -232,13 +339,14 @@
*
* @param list the list
* @param elem a pointer to the element to add
- * @return zero on success, non-zero on memory allocation failure
+ * @retval zero success
+ * @retval non-zero memory allocation failure
* @see cxListAddArray()
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline int cxListAdd(
CxList *list,
- void const *elem
+ const void *elem
) {
return list->cl->insert_element(list, list->collection.size, elem);
}
@@ -249,9 +357,9 @@
* This method is more efficient than invoking cxListAdd() multiple times.
*
* If there is not enough memory to add all elements, the returned value is
- * less than \p n.
+ * less than @p n.
*
- * If this list is storing pointers instead of objects \p array is expected to
+ * If this list is storing pointers instead of objects @p array is expected to
* be an array of pointers.
*
* @param list the list
@@ -259,10 +367,10 @@
* @param n the number of elements to add
* @return the number of added elements
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline size_t cxListAddArray(
CxList *list,
- void const *array,
+ const void *array,
size_t n
) {
return list->cl->insert_array(list, list->collection.size, array, n);
@@ -271,36 +379,53 @@
/**
* Inserts an item at the specified index.
*
- * If \p index equals the list \c size, this is effectively cxListAdd().
+ * If @p index equals the list @c size, this is effectively cxListAdd().
*
* @param list the list
* @param index the index the element shall have
* @param elem a pointer to the element to add
- * @return zero on success, non-zero on memory allocation failure
- * or when the index is out of bounds
+ * @retval zero success
+ * @retval non-zero memory allocation failure or the index is out of bounds
* @see cxListInsertAfter()
* @see cxListInsertBefore()
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline int cxListInsert(
CxList *list,
size_t index,
- void const *elem
+ const void *elem
) {
return list->cl->insert_element(list, index, elem);
}
/**
+ * Inserts an item into a sorted list.
+ *
+ * @param list the list
+ * @param elem a pointer to the element to add
+ * @retval zero success
+ * @retval non-zero memory allocation failure
+ */
+cx_attr_nonnull
+static inline int cxListInsertSorted(
+ CxList *list,
+ const void *elem
+) {
+ const void *data = list->collection.store_pointer ? &elem : elem;
+ return list->cl->insert_sorted(list, data, 1) == 0;
+}
+
+/**
* Inserts multiple items to the list at the specified index.
- * If \p index equals the list size, this is effectively cxListAddArray().
+ * If @p index equals the list size, this is effectively cxListAddArray().
*
* This method is usually more efficient than invoking cxListInsert()
* multiple times.
*
* If there is not enough memory to add all elements, the returned value is
- * less than \p n.
+ * less than @p n.
*
- * If this list is storing pointers instead of objects \p array is expected to
+ * If this list is storing pointers instead of objects @p array is expected to
* be an array of pointers.
*
* @param list the list
@@ -309,35 +434,62 @@
* @param n the number of elements to add
* @return the number of added elements
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline size_t cxListInsertArray(
CxList *list,
size_t index,
- void const *array,
+ const void *array,
size_t n
) {
return list->cl->insert_array(list, index, array, n);
}
/**
+ * Inserts a sorted array into a sorted list.
+ *
+ * This method is usually more efficient than inserting each element separately,
+ * because consecutive chunks of sorted data are inserted in one pass.
+ *
+ * If there is not enough memory to add all elements, the returned value is
+ * less than @p n.
+ *
+ * If this list is storing pointers instead of objects @p array is expected to
+ * be an array of pointers.
+ *
+ * @param list the list
+ * @param array a pointer to the elements to add
+ * @param n the number of elements to add
+ * @return the number of added elements
+ */
+cx_attr_nonnull
+static inline size_t cxListInsertSortedArray(
+ CxList *list,
+ const void *array,
+ size_t n
+) {
+ return list->cl->insert_sorted(list, array, n);
+}
+
+/**
* Inserts an element after the current location of the specified iterator.
*
* The used iterator remains operational, but all other active iterators should
* be considered invalidated.
*
- * If \p iter is not a list iterator, the behavior is undefined.
- * If \p iter is a past-the-end iterator, the new element gets appended to the list.
+ * If @p iter is not a list iterator, the behavior is undefined.
+ * If @p iter is a past-the-end iterator, the new element gets appended to the list.
*
* @param iter an iterator
* @param elem the element to insert
- * @return zero on success, non-zero on memory allocation failure
+ * @retval zero success
+ * @retval non-zero memory allocation failure
* @see cxListInsert()
* @see cxListInsertBefore()
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline int cxListInsertAfter(
CxIterator *iter,
- void const *elem
+ const void *elem
) {
return ((struct cx_list_s *) iter->src_handle.m)->cl->insert_iter(iter, elem, 0);
}
@@ -348,19 +500,20 @@
* The used iterator remains operational, but all other active iterators should
* be considered invalidated.
*
- * If \p iter is not a list iterator, the behavior is undefined.
- * If \p iter is a past-the-end iterator, the new element gets appended to the list.
+ * If @p iter is not a list iterator, the behavior is undefined.
+ * If @p iter is a past-the-end iterator, the new element gets appended to the list.
*
* @param iter an iterator
* @param elem the element to insert
- * @return zero on success, non-zero on memory allocation failure
+ * @retval zero success
+ * @retval non-zero memory allocation failure
* @see cxListInsert()
* @see cxListInsertAfter()
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline int cxListInsertBefore(
CxIterator *iter,
- void const *elem
+ const void *elem
) {
return ((struct cx_list_s *) iter->src_handle.m)->cl->insert_iter(iter, elem, 1);
}
@@ -373,25 +526,95 @@
*
* @param list the list
* @param index the index of the element
- * @return zero on success, non-zero if the index is out of bounds
+ * @retval zero success
+ * @retval non-zero index out of bounds
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline int cxListRemove(
CxList *list,
size_t index
) {
- return list->cl->remove(list, index);
+ return list->cl->remove(list, index, 1, NULL) == 0;
+}
+
+/**
+ * Removes and returns the element at the specified index.
+ *
+ * No destructor is called and instead the element is copied to the
+ * @p targetbuf which MUST be large enough to hold the removed element.
+ *
+ * @param list the list
+ * @param index the index of the element
+ * @param targetbuf a buffer where to copy the element
+ * @retval zero success
+ * @retval non-zero index out of bounds
+ */
+cx_attr_nonnull
+cx_attr_access_w(3)
+static inline int cxListRemoveAndGet(
+ CxList *list,
+ size_t index,
+ void *targetbuf
+) {
+ return list->cl->remove(list, index, 1, targetbuf) == 0;
+}
+
+/**
+ * Removes multiple element starting at the specified index.
+ *
+ * If an element destructor function is specified, it is called for each
+ * element. It is guaranteed that the destructor is called before removing
+ * the element, however, due to possible optimizations it is neither guaranteed
+ * that the destructors are invoked for all elements before starting to remove
+ * them, nor that the element is removed immediately after the destructor call
+ * before proceeding to the next element.
+ *
+ * @param list the list
+ * @param index the index of the element
+ * @param num the number of elements to remove
+ * @return the actual number of removed elements
+ */
+cx_attr_nonnull
+static inline size_t cxListRemoveArray(
+ CxList *list,
+ size_t index,
+ size_t num
+) {
+ return list->cl->remove(list, index, num, NULL);
+}
+
+/**
+ * Removes and returns multiple element starting at the specified index.
+ *
+ * No destructor is called and instead the elements are copied to the
+ * @p targetbuf which MUST be large enough to hold all removed elements.
+ *
+ * @param list the list
+ * @param index the index of the element
+ * @param num the number of elements to remove
+ * @param targetbuf a buffer where to copy the elements
+ * @return the actual number of removed elements
+ */
+cx_attr_nonnull
+cx_attr_access_w(4)
+static inline size_t cxListRemoveArrayAndGet(
+ CxList *list,
+ size_t index,
+ size_t num,
+ void *targetbuf
+) {
+ return list->cl->remove(list, index, num, targetbuf);
}
/**
* Removes all elements from this list.
*
- * If an element destructor function is specified, it is called for each
+ * If element destructor functions are specified, they are called for each
* element before removing them.
*
* @param list the list
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline void cxListClear(CxList *list) {
list->cl->clear(list);
}
@@ -405,9 +628,11 @@
* @param list the list
* @param i the index of the first element
* @param j the index of the second element
- * @return zero on success, non-zero if one of the indices is out of bounds
+ * @retval zero success
+ * @retval non-zero one of the indices is out of bounds
+ * or the swap needed extra memory but allocation failed
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline int cxListSwap(
CxList *list,
size_t i,
@@ -421,11 +646,11 @@
*
* @param list the list
* @param index the index of the element
- * @return a pointer to the element or \c NULL if the index is out of bounds
+ * @return a pointer to the element or @c NULL if the index is out of bounds
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline void *cxListAt(
- CxList *list,
+ const CxList *list,
size_t index
) {
return list->cl->at(list, index);
@@ -442,9 +667,10 @@
* @param index the index where the iterator shall point at
* @return a new iterator
*/
-__attribute__((__nonnull__, __warn_unused_result__))
+cx_attr_nonnull
+cx_attr_nodiscard
static inline CxIterator cxListIteratorAt(
- CxList const *list,
+ const CxList *list,
size_t index
) {
return list->cl->iterator(list, index, false);
@@ -461,9 +687,10 @@
* @param index the index where the iterator shall point at
* @return a new iterator
*/
-__attribute__((__nonnull__, __warn_unused_result__))
+cx_attr_nonnull
+cx_attr_nodiscard
static inline CxIterator cxListBackwardsIteratorAt(
- CxList const *list,
+ const CxList *list,
size_t index
) {
return list->cl->iterator(list, index, true);
@@ -480,7 +707,8 @@
* @param index the index where the iterator shall point at
* @return a new iterator
*/
-__attribute__((__nonnull__, __warn_unused_result__))
+cx_attr_nonnull
+cx_attr_nodiscard
CxIterator cxListMutIteratorAt(
CxList *list,
size_t index
@@ -498,7 +726,8 @@
* @param index the index where the iterator shall point at
* @return a new iterator
*/
-__attribute__((__nonnull__, __warn_unused_result__))
+cx_attr_nonnull
+cx_attr_nodiscard
CxIterator cxListMutBackwardsIteratorAt(
CxList *list,
size_t index
@@ -514,8 +743,9 @@
* @param list the list
* @return a new iterator
*/
-__attribute__((__nonnull__, __warn_unused_result__))
-static inline CxIterator cxListIterator(CxList const *list) {
+cx_attr_nonnull
+cx_attr_nodiscard
+static inline CxIterator cxListIterator(const CxList *list) {
return list->cl->iterator(list, 0, false);
}
@@ -529,7 +759,8 @@
* @param list the list
* @return a new iterator
*/
-__attribute__((__nonnull__, __warn_unused_result__))
+cx_attr_nonnull
+cx_attr_nodiscard
static inline CxIterator cxListMutIterator(CxList *list) {
return cxListMutIteratorAt(list, 0);
}
@@ -545,8 +776,9 @@
* @param list the list
* @return a new iterator
*/
-__attribute__((__nonnull__, __warn_unused_result__))
-static inline CxIterator cxListBackwardsIterator(CxList const *list) {
+cx_attr_nonnull
+cx_attr_nodiscard
+static inline CxIterator cxListBackwardsIterator(const CxList *list) {
return list->cl->iterator(list, list->collection.size - 1, true);
}
@@ -560,13 +792,14 @@
* @param list the list
* @return a new iterator
*/
-__attribute__((__nonnull__, __warn_unused_result__))
+cx_attr_nonnull
+cx_attr_nodiscard
static inline CxIterator cxListMutBackwardsIterator(CxList *list) {
return cxListMutBackwardsIteratorAt(list, list->collection.size - 1);
}
/**
- * Returns the index of the first element that equals \p elem.
+ * Returns the index of the first element that equals @p elem.
*
* Determining equality is performed by the list's comparator function.
*
@@ -575,16 +808,17 @@
* @return the index of the element or a negative
* value when the element is not found
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
+cx_attr_nodiscard
static inline ssize_t cxListFind(
- CxList const *list,
- void const *elem
+ const CxList *list,
+ const void *elem
) {
return list->cl->find_remove((CxList*)list, elem, false);
}
/**
- * Removes and returns the index of the first element that equals \p elem.
+ * Removes and returns the index of the first element that equals @p elem.
*
* Determining equality is performed by the list's comparator function.
*
@@ -593,22 +827,22 @@
* @return the index of the now removed element or a negative
* value when the element is not found or could not be removed
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline ssize_t cxListFindRemove(
CxList *list,
- void const *elem
+ const void *elem
) {
return list->cl->find_remove(list, elem, true);
}
/**
- * Sorts the list in-place.
+ * Sorts the list.
*
- * \remark The underlying sort algorithm is implementation defined.
+ * @remark The underlying sort algorithm is implementation defined.
*
* @param list the list
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline void cxListSort(CxList *list) {
list->cl->sort(list);
}
@@ -618,7 +852,7 @@
*
* @param list the list
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline void cxListReverse(CxList *list) {
list->cl->reverse(list);
}
@@ -631,34 +865,37 @@
*
* @param list the list
* @param other the list to compare to
- * @return zero, if both lists are equal element wise,
- * negative if the first list is smaller, positive if the first list is larger
+ * @retval zero both lists are equal element wise
+ * @retval negative the first list is smaller
+ * or the first non-equal element in the first list is smaller
+ * @retval positive the first list is larger
+ * or the first non-equal element in the first list is larger
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
+cx_attr_nodiscard
int cxListCompare(
- CxList const *list,
- CxList const *other
+ const CxList *list,
+ const CxList *other
);
/**
* Deallocates the memory of the specified list structure.
*
- * Also calls content a destructor function, depending on the configuration
- * in CxList.content_destructor_type.
- *
- * This function itself is a destructor function for the CxList.
+ * Also calls the content destructor functions for each element, if specified.
*
- * @param list the list which shall be destroyed
+ * @param list the list which shall be freed
*/
-__attribute__((__nonnull__))
-void cxListDestroy(CxList *list);
+void cxListFree(CxList *list);
/**
* A shared instance of an empty list.
*
- * Writing to that list is undefined.
+ * Writing to that list is not allowed.
+ *
+ * You can use this is a placeholder for initializing CxList pointers
+ * for which you do not want to reserve memory right from the beginning.
*/
-extern CxList * const cxEmptyList;
+extern CxList *const cxEmptyList;
#ifdef __cplusplus