diff -r ec1f2015ec79 -r 75da57d4634e src/cx/list.h --- a/src/cx/list.h Sun Oct 06 19:17:41 2024 +0200 +++ b/src/cx/list.h Mon Oct 07 20:20:21 2024 +0200 @@ -118,11 +118,20 @@ ); /** - * 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 ); /** @@ -512,7 +521,73 @@ 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 + * @return zero on success, non-zero if the index is out of bounds + */ +__attribute__((__nonnull__)) +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 + */ +__attribute__((__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 + */ +__attribute__((__nonnull__)) +static inline size_t cxListRemoveArrayAndGet( + CxList *list, + size_t index, + size_t num, + void *targetbuf +) { + return list->cl->remove(list, index, num, targetbuf); } /**