--- a/src/cx/list.h Thu Nov 07 20:22:56 2024 +0100
+++ b/src/cx/list.h Thu Nov 07 22:46:58 2024 +0100
@@ -52,6 +52,9 @@
* Structure for holding the base data of a list.
*/
struct cx_list_s {
+ /**
+ * Common members for collections.
+ */
CX_COLLECTION_BASE;
/**
* The list class definition.
@@ -73,12 +76,14 @@
* Implementations SHALL invoke the content destructor functions if provided
* and SHALL deallocate the list memory.
*/
+ cx_attr_nonnull
void (*destructor)(struct cx_list_s *list);
/**
* Member function for inserting a single element.
* Implementors SHOULD see to performant implementations for corner cases.
*/
+ cx_attr_nonnull
int (*insert_element)(
struct cx_list_s *list,
size_t index,
@@ -90,6 +95,7 @@
* Implementors SHOULD see to performant implementations for corner cases.
* @see cx_list_default_insert_array()
*/
+ cx_attr_nonnull
size_t (*insert_array)(
struct cx_list_s *list,
size_t index,
@@ -102,6 +108,7 @@
*
* @see cx_list_default_insert_sorted()
*/
+ cx_attr_nonnull
size_t (*insert_sorted)(
struct cx_list_s *list,
const void *sorted_data,
@@ -111,6 +118,7 @@
/**
* Member function for inserting an element relative to an iterator position.
*/
+ cx_attr_nonnull
int (*insert_iter)(
struct cx_iterator_s *iter,
const void *elem,
@@ -127,6 +135,8 @@
* The function SHALL return the actual number of elements removed, which
* might be lower than \p num when going out of bounds.
*/
+ cx_attr_nonnull_arg(1)
+ cx_attr_access_w(4)
size_t (*remove)(
struct cx_list_s *list,
size_t index,
@@ -137,12 +147,14 @@
/**
* Member function for removing all elements.
*/
+ cx_attr_nonnull
void (*clear)(struct cx_list_s *list);
/**
* Member function for swapping two elements.
* @see cx_list_default_swap()
*/
+ cx_attr_nonnull
int (*swap)(
struct cx_list_s *list,
size_t i,
@@ -152,6 +164,8 @@
/**
* Member function for element lookup.
*/
+ cx_attr_nonnull
+ cx_attr_nodiscard
void *(*at)(
const struct cx_list_s *list,
size_t index
@@ -160,6 +174,8 @@
/**
* Member function for finding and optionally removing an element.
*/
+ cx_attr_nonnull
+ cx_attr_nodiscard
ssize_t (*find_remove)(
struct cx_list_s *list,
const void *elem,
@@ -170,6 +186,7 @@
* Member function for sorting the list in-place.
* @see cx_list_default_sort()
*/
+ cx_attr_nonnull
void (*sort)(struct cx_list_s *list);
/**
@@ -177,6 +194,7 @@
* to another list of the same type.
* If set to \c NULL, comparison won't be optimized.
*/
+ cx_attr_nonnull
int (*compare)(
const struct cx_list_s *list,
const struct cx_list_s *other
@@ -185,11 +203,13 @@
/**
* Member function for reversing the order of the items.
*/
+ cx_attr_nonnull
void (*reverse)(struct cx_list_s *list);
/**
* Member function for returning an iterator pointing to the specified index.
*/
+ cx_attr_nonnull
struct cx_iterator_s (*iterator)(
const struct cx_list_s *list,
size_t index,
@@ -211,7 +231,7 @@
* @param n the number of elements to insert
* @return the number of elements actually inserted
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
size_t cx_list_default_insert_array(
struct cx_list_s *list,
size_t index,
@@ -235,7 +255,7 @@
* @param n the number of elements to insert
* @return the number of elements actually inserted
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
size_t cx_list_default_insert_sorted(
struct cx_list_s *list,
const void *sorted_data,
@@ -253,7 +273,7 @@
*
* @param list the list that shall be sorted
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
void cx_list_default_sort(struct cx_list_s *list);
/**
@@ -268,7 +288,7 @@
* @return zero on success, non-zero when indices are out of bounds or memory
* allocation for the temporary buffer fails
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
int cx_list_default_swap(struct cx_list_s *list, size_t i, size_t j);
/**
@@ -285,7 +305,7 @@
* @param list the list
* @see cxListStorePointers()
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
void cxListStoreObjects(CxList *list);
/**
@@ -300,7 +320,7 @@
* @param list the list
* @see cxListStoreObjects()
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
void cxListStorePointers(CxList *list);
/**
@@ -310,7 +330,7 @@
* @return true, if this list is storing pointers
* @see cxListStorePointers()
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline bool cxListIsStoringPointers(const CxList *list) {
return list->collection.store_pointer;
}
@@ -321,7 +341,7 @@
* @param list the list
* @return the number of currently stored elements
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline size_t cxListSize(const CxList *list) {
return list->collection.size;
}
@@ -334,7 +354,7 @@
* @return zero on success, non-zero on memory allocation failure
* @see cxListAddArray()
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline int cxListAdd(
CxList *list,
const void *elem
@@ -358,7 +378,7 @@
* @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,
const void *array,
@@ -380,7 +400,7 @@
* @see cxListInsertAfter()
* @see cxListInsertBefore()
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline int cxListInsert(
CxList *list,
size_t index,
@@ -396,7 +416,7 @@
* @param elem a pointer to the element to add
* @return zero on success, non-zero on memory allocation failure
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline int cxListInsertSorted(
CxList *list,
const void *elem
@@ -424,7 +444,7 @@
* @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,
@@ -451,7 +471,7 @@
* @param n the number of elements to add
* @return the number of added elements
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline size_t cxListInsertSortedArray(
CxList *list,
const void *array,
@@ -475,7 +495,7 @@
* @see cxListInsert()
* @see cxListInsertBefore()
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline int cxListInsertAfter(
CxIterator *iter,
const void *elem
@@ -498,7 +518,7 @@
* @see cxListInsert()
* @see cxListInsertAfter()
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline int cxListInsertBefore(
CxIterator *iter,
const void *elem
@@ -516,7 +536,7 @@
* @param index the index of the element
* @return zero on success, non-zero if the index is out of bounds
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline int cxListRemove(
CxList *list,
size_t index
@@ -535,7 +555,8 @@
* @param targetbuf a buffer where to copy the element
* @return zero on success, non-zero if the index is out of bounds
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
+cx_attr_access_w(3)
static inline int cxListRemoveAndGet(
CxList *list,
size_t index,
@@ -559,7 +580,7 @@
* @param num the number of elements to remove
* @return the actual number of removed elements
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline size_t cxListRemoveArray(
CxList *list,
size_t index,
@@ -580,7 +601,8 @@
* @param targetbuf a buffer where to copy the elements
* @return the actual number of removed elements
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
+cx_attr_access_w(4)
static inline size_t cxListRemoveArrayAndGet(
CxList *list,
size_t index,
@@ -598,7 +620,7 @@
*
* @param list the list
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline void cxListClear(CxList *list) {
list->cl->clear(list);
}
@@ -614,7 +636,7 @@
* @param j the index of the second element
* @return zero on success, non-zero if one of the indices is out of bounds
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline int cxListSwap(
CxList *list,
size_t i,
@@ -630,9 +652,9 @@
* @param index the index of the element
* @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);
@@ -649,7 +671,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
static inline CxIterator cxListIteratorAt(
const CxList *list,
size_t index
@@ -668,7 +691,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
static inline CxIterator cxListBackwardsIteratorAt(
const CxList *list,
size_t index
@@ -687,7 +711,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
@@ -705,7 +730,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
@@ -721,7 +747,8 @@
* @param list the list
* @return a new iterator
*/
-__attribute__((__nonnull__, __warn_unused_result__))
+cx_attr_nonnull
+cx_attr_nodiscard
static inline CxIterator cxListIterator(const CxList *list) {
return list->cl->iterator(list, 0, false);
}
@@ -736,7 +763,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);
}
@@ -752,7 +780,8 @@
* @param list the list
* @return a new iterator
*/
-__attribute__((__nonnull__, __warn_unused_result__))
+cx_attr_nonnull
+cx_attr_nodiscard
static inline CxIterator cxListBackwardsIterator(const CxList *list) {
return list->cl->iterator(list, list->collection.size - 1, true);
}
@@ -767,7 +796,8 @@
* @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);
}
@@ -782,7 +812,8 @@
* @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(
const CxList *list,
const void *elem
@@ -800,7 +831,7 @@
* @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,
const void *elem
@@ -815,7 +846,7 @@
*
* @param list the list
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline void cxListSort(CxList *list) {
list->cl->sort(list);
}
@@ -825,7 +856,7 @@
*
* @param list the list
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
static inline void cxListReverse(CxList *list) {
list->cl->reverse(list);
}
@@ -841,7 +872,8 @@
* @return zero, if both lists are equal element wise,
* negative if the first list is smaller, positive if the first list is larger
*/
-__attribute__((__nonnull__))
+cx_attr_nonnull
+cx_attr_nodiscard
int cxListCompare(
const CxList *list,
const CxList *other
@@ -857,15 +889,17 @@
*
* @param list the list which shall be destroyed
*/
-__attribute__((__nonnull__))
-void cxListDestroy(CxList *list);
+static inline void cxListDestroy(CxList *list) {
+ if (list == NULL) return;
+ list->cl->destructor(list);
+}
/**
* A shared instance of an empty list.
*
- * Writing to that list is undefined.
+ * Writing to that list is not allowed.
*/
-extern CxList * const cxEmptyList;
+extern CxList *const cxEmptyList;
#ifdef __cplusplus