ucx: comparison src/cx/list.h

-:2ca6fa71e55e
+:2872f287fadc
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */
 /**
-* \file list.h
+* @file list.h
-* \brief Interface for list implementations.
+* @brief Interface for list implementations.
-* \author Mike Becker
+* @author Mike Becker
-* \author Olaf Wintermann
+* @author Olaf Wintermann
-* \copyright 2-Clause BSD License
+* @copyright 2-Clause BSD License
 */
 #ifndef UCX_LIST_H
 #define UCX_LIST_H
 * Destructor function.
 *
 * Implementations SHALL invoke the content destructor functions if provided
 * and SHALL deallocate the entire list memory.
 */
-cx_attr_nonnull
 void (*deallocate)(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
 );
 /**
 * Member function for removing elements.
 *
-* Implementations SHALL check if \p targetbuf is set and copy the 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.
+* 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.
+* 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.
+* Member function for sorting the list.
+*
 * @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.
+* 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
 );
 * 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.
+* 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
 * 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
-* @return zero on success, non-zero when indices are out of bounds or memory
+* @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);
 /**
 * Adds an item to the end of the list.
 *
 * @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()
 */
 cx_attr_nonnull
 static inline int cxListAdd(
 CxList *list,
 * Adds multiple items to the end of the list.
 *
 * 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
 * @param array a pointer to the elements to add
 * @param n the number of elements to add
 }
 /**
 * 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
+* @retval zero success
-* or when the index is out of bounds
+* @retval non-zero memory allocation failure or the index is out of bounds
 * @see cxListInsertAfter()
 * @see cxListInsertBefore()
 */
 cx_attr_nonnull
 static inline int cxListInsert(
 /**
 * Inserts an item into a sorted list.
 *
 * @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
 */
 cx_attr_nonnull
 static inline int cxListInsertSorted(
 CxList *list,
 const void *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
 * @param index the index where to add the elements
 * @param array a pointer to the elements to add
 *
 * 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.
+* 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
 * @param array a pointer to the elements to add
 * @param n the number of elements to add
 * 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 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 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()
 */
 cx_attr_nonnull
 static inline int cxListInsertAfter(
 * Inserts an element before 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 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 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()
 */
 cx_attr_nonnull
 static inline int cxListInsertBefore(
 * If an element destructor function is specified, it is called before
 * removing the element.
 *
 * @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
 */
 cx_attr_nonnull
 static inline int cxListRemove(
 CxList *list,
 size_t index
 /**
 * 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.
+* @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
-* @return zero on success, non-zero if the index is out of bounds
+* @retval zero success
+* @retval non-zero index out of bounds
 */
 cx_attr_nonnull
 cx_attr_access_w(3)
 static inline int cxListRemoveAndGet(
 CxList *list,
 /**
 * 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.
+* @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
 }
 /**
 * 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
 */
 cx_attr_nonnull
 * it is necessary.
 *
 * @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
 */
 cx_attr_nonnull
 static inline int cxListSwap(
 CxList *list,
 size_t i,
 /**
 * Returns a pointer to the element at the specified index.
 *
 * @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
 */
 cx_attr_nonnull
 static inline void *cxListAt(
 const CxList *list,
 size_t index
 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.
 *
 * @param list the list
 * @param elem the element to find
 ) {
 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.
 *
 * @param list the list
 * @param elem the element to find and remove
 ) {
 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
 */
 cx_attr_nonnull
 static inline void cxListSort(CxList *list) {
 * First, the list sizes are compared.
 * If they match, the lists are compared element-wise.
 *
 * @param list the list
 * @param other the list to compare to
-* @return zero, if both lists are equal element wise,
+* @retval zero both lists are equal element wise
-* negative if the first list is smaller, positive if the first list is larger
+* @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
 */
 cx_attr_nonnull
 cx_attr_nodiscard
 int cxListCompare(
 const CxList *list,
 );
 /**
 * Deallocates the memory of the specified list structure.
 *
-* Also calls the content destructor function for each element, if specified.
+* Also calls the content destructor functions for each element, if specified.
 *
 * @param list the list which shall be freed
 */
 static inline void cxListFree(CxList *list) {
 if (list == NULL) return;
 /**
 * A shared instance of an empty list.
 *
 * 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;
 #ifdef __cplusplus

Mercurial > hg > ucx / file comparison

comparison: src/cx/list.h

src/cx/list.h