ucx: comparison src/cx/list.h

-:e8f354a25ac8
+:68754c7de906
 /**
 * Structure for holding the base data of a list.
 */
 struct cx_list_s {
+/**
+* Common members for collections.
+*/
 CX_COLLECTION_BASE;
 /**
 * The list class definition.
 */
 const cx_list_class *cl;
 * Destructor function.
 *
 * 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,
 const void *data
 );
 /**
 * Member function for inserting multiple elements.
 * 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,
 const void *data,
 size_t n
 /**
 * Member function for inserting sorted elements into a sorted list.
 *
 * @see cx_list_default_insert_sorted()
 */
+cx_attr_nonnull
 size_t (*insert_sorted)(
 struct cx_list_s *list,
 const void *sorted_data,
 size_t n
 );
 /**
 * 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,
 int prepend
 );
 * 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.
 */
+cx_attr_nonnull_arg(1)
+cx_attr_access_w(4)
 size_t (*remove)(
 struct cx_list_s *list,
 size_t index,
 size_t num,
 void *targetbuf
 );
 /**
 * 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,
 size_t j
 );
 /**
 * Member function for element lookup.
 */
+cx_attr_nonnull
+cx_attr_nodiscard
 void *(*at)(
 const struct cx_list_s *list,
 size_t index
 );
 /**
 * 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,
 bool remove
 );
 /**
 * Member function for sorting the list in-place.
 * @see cx_list_default_sort()
 */
+cx_attr_nonnull
 void (*sort)(struct cx_list_s *list);
 /**
 * 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)(
 const struct cx_list_s *list,
 const struct cx_list_s *other
 );
 /**
 * 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,
 bool backward
 );
 * @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
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 size_t cx_list_default_insert_array(
 struct cx_list_s *list,
 size_t index,
 const void *data,
 size_t n
 * @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
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 size_t cx_list_default_insert_sorted(
 struct cx_list_s *list,
 const void *sorted_data,
 size_t n
 );
 * 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
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 void cx_list_default_sort(struct cx_list_s *list);
 /**
 * Default unoptimized swap implementation.
 *
 * @param i index of one element
 * @param j index of the other element
 * @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);
 /**
 * Common type for all list implementations.
 */
 * within this list.
 *
 * @param list the list
 * @see cxListStorePointers()
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 void cxListStoreObjects(CxList *list);
 /**
 * Advises the list to only store pointers to the objects.
 *
 * objects is undefined.
 *
 * @param list the list
 * @see cxListStoreObjects()
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 void cxListStorePointers(CxList *list);
 /**
 * Returns true, if this list is storing pointers instead of the actual data.
 *
 * @param list
 * @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;
 }
 /**
 * Returns the number of elements currently stored in the list.
 *
 * @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;
 }
 /**
 * @param list the list
 * @param elem a pointer to the element to add
 * @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
 ) {
 return list->cl->insert_element(list, list->collection.size, elem);
 * @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
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 static inline size_t cxListAddArray(
 CxList *list,
 const void *array,
 size_t n
 ) {
 * @return zero on success, non-zero on memory allocation failure
 * or when the index is out of bounds
 * @see cxListInsertAfter()
 * @see cxListInsertBefore()
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 static inline int cxListInsert(
 CxList *list,
 size_t index,
 const void *elem
 ) {
 *
 * @param list the list
 * @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
 ) {
 const void *data = list->collection.store_pointer ? &elem : elem;
 * @param index the index where to add the elements
 * @param array a pointer to the elements to add
 * @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,
 const void *array,
 size_t n
 * @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
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 static inline size_t cxListInsertSortedArray(
 CxList *list,
 const void *array,
 size_t n
 ) {
 * @param elem the element to insert
 * @return zero on success, non-zero on memory allocation failure
 * @see cxListInsert()
 * @see cxListInsertBefore()
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 static inline int cxListInsertAfter(
 CxIterator *iter,
 const void *elem
 ) {
 return ((struct cx_list_s *) iter->src_handle.m)->cl->insert_iter(iter, elem, 0);
 * @param elem the element to insert
 * @return zero on success, non-zero on memory allocation failure
 * @see cxListInsert()
 * @see cxListInsertAfter()
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 static inline int cxListInsertBefore(
 CxIterator *iter,
 const void *elem
 ) {
 return ((struct cx_list_s *) iter->src_handle.m)->cl->insert_iter(iter, elem, 1);
 *
 * @param list the list
 * @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
 ) {
 return list->cl->remove(list, index, 1, NULL) == 0;
 * @param list the list
 * @param index the index of the element
 * @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,
 void *targetbuf
 ) {
 * @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
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 static inline size_t cxListRemoveArray(
 CxList *list,
 size_t index,
 size_t num
 ) {
 * @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
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
+cx_attr_access_w(4)
 static inline size_t cxListRemoveArrayAndGet(
 CxList *list,
 size_t index,
 size_t num,
 void *targetbuf
 * If an element destructor function is specified, it is 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);
 }
 /**
 * @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
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 static inline int cxListSwap(
 CxList *list,
 size_t i,
 size_t j
 ) {
 *
 * @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
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 static inline void *cxListAt(
-CxList *list,
+const CxList *list,
 size_t index
 ) {
 return list->cl->at(list, index);
 }
 *
 * @param list the list
 * @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
 ) {
 return list->cl->iterator(list, index, false);
 *
 * @param list the list
 * @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
 ) {
 return list->cl->iterator(list, index, true);
 *
 * @param list the list
 * @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
 );
 *
 * @param list the list
 * @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
 );
 * If the list is empty, a past-the-end iterator will be returned.
 *
 * @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);
 }
 /**
 * If the list is empty, a past-the-end iterator will be returned.
 *
 * @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);
 }
 * If the list is empty, a past-the-end iterator will be returned.
 *
 * @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);
 }
 /**
 * If the list is empty, a past-the-end iterator will be returned.
 *
 * @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);
 }
 /**
 * @param list the list
 * @param elem the element to find
 * @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
 ) {
 return list->cl->find_remove((CxList*)list, elem, false);
 * @param list the list
 * @param elem the element to find and remove
 * @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
 ) {
 return list->cl->find_remove(list, elem, true);
 *
 * \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);
 }
 /**
 * Reverses the order of the items.
 *
 * @param list the list
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 static inline void cxListReverse(CxList *list) {
 list->cl->reverse(list);
 }
 /**
 * @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
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
+cx_attr_nodiscard
 int cxListCompare(
 const CxList *list,
 const CxList *other
 );
 *
 * This function itself is a destructor function for the CxList.
 *
 * @param list the list which shall be destroyed
 */
-__attribute__((__nonnull__))
+static inline void cxListDestroy(CxList *list) {
-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
 } // extern "C"
 #endif

Mercurial > hg > ucx / file comparison

comparison: src/cx/list.h

src/cx/list.h