dav: comparison ucx/cx/list.h

-:591377a27fa3
+:da79af4baec8
 */
 void (*deallocate)(struct cx_list_s *list);
 /**
 * Member function for inserting a single element.
-*/
+* The data pointer may be @c NULL in which case the function shall only allocate memory.
-int (*insert_element)(
+* Returns a pointer to the allocated memory or @c NULL if allocation fails.
+*/
+void *(*insert_element)(
 struct cx_list_s *list,
 size_t index,
 const void *data
 );
 /**
 * 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
 );
 const struct cx_list_s *list,
 size_t index,
 bool backward
 );
 };
+/**
+* Common type for all list implementations.
+*/
+typedef struct cx_list_s CxList;
+/**
+* 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.
+*/
+cx_attr_export
+extern CxList *const cxEmptyList;
 /**
 * Default implementation of an array insert.
 *
 * This function uses the element insert function for each element of the array.
 cx_compare_func comparator,
 size_t elem_size
 );
 /**
-* Common type for all list implementations.
-*/
-typedef struct cx_list_s CxList;
-/**
 * Returns the number of elements currently stored in the list.
 *
 * @param list the list
 * @return the number of currently stored elements
 */
 * @param list the list
 * @param elem a pointer to the element to add
 * @retval zero success
 * @retval non-zero memory allocation failure
 * @see cxListAddArray()
+* @see cxListEmplace()
 */
 cx_attr_nonnull
 static inline int cxListAdd(
 CxList *list,
 const void *elem
 ) {
 list->collection.sorted = false;
-return list->cl->insert_element(list, list->collection.size, elem);
+return list->cl->insert_element(list, list->collection.size, elem) == NULL;
 }
 /**
 * Adds multiple items to the end of the list.
 *
 * @param elem a pointer to the element to add
 * @retval zero success
 * @retval non-zero memory allocation failure or the index is out of bounds
 * @see cxListInsertAfter()
 * @see cxListInsertBefore()
+* @see cxListEmplaceAt()
 */
 cx_attr_nonnull
 static inline int cxListInsert(
 CxList *list,
 size_t index,
 const void *elem
 ) {
 list->collection.sorted = false;
-return list->cl->insert_element(list, index, elem);
+return list->cl->insert_element(list, index, elem) == NULL;
+}
+/**
+* Allocates memory for an element at the specified index and returns a pointer to that memory.
+*
+* @remark When the list is storing pointers, this will return a @c void**.
+*
+* @param list the list
+* @param index the index where to emplace the element
+* @return a pointer to the allocated memory; @c NULL when the operation fails, or the index is out-of-bounds
+* @see cxListEmplace()
+* @see cxListInsert()
+*/
+cx_attr_nonnull
+static inline void *cxListEmplaceAt(CxList *list, size_t index) {
+list->collection.sorted = false;
+return list->cl->insert_element(list, index, NULL);
+}
+/**
+* Allocates memory for an element at the end of the list and returns a pointer to that memory.
+*
+* @remark When the list is storing pointers, this will return a @c void**.
+*
+* @param list the list
+* @return a pointer to the allocated memory; @c NULL when the operation fails, or the index is out-of-bounds
+* @see cxListEmplaceAt()
+* @see cxListAdd()
+*/
+cx_attr_nonnull
+static inline void *cxListEmplace(CxList *list) {
+list->collection.sorted = false;
+return list->cl->insert_element(list, list->collection.size, NULL);
 }
 /**
 * Inserts an item into a sorted list.
 *
 }
 /**
 * Removes and returns the element at the specified index.
 *
-* No destructor is called and instead the element is copied to the
+* No destructor is called, and instead the element is copied to the
 * @p targetbuf which MUST be large enough to hold the removed element.
+* If the list is storing pointers, only the pointer is copied to @p targetbuf.
 *
 * @param list the list
 * @param index the index of the element
 * @param targetbuf a buffer where to copy the element
 * @retval zero success
 ) {
 return list->cl->remove(list, index, 1, targetbuf) == 0;
 }
 /**
+* Removes and returns the first element of the list.
+*
+* No destructor is called, and instead the element is copied to the
+* @p targetbuf which MUST be large enough to hold the removed element.
+* If the list is storing pointers, only the pointer is copied to @p targetbuf.
+*
+* @param list the list
+* @param targetbuf a buffer where to copy the element
+* @retval zero success
+* @retval non-zero list is empty
+* @see cxListPopFront()
+* @see cxListRemoveAndGetLast()
+*/
+cx_attr_nonnull
+cx_attr_access_w(2)
+static inline int cxListRemoveAndGetFirst(
+CxList *list,
+void *targetbuf
+) {
+return list->cl->remove(list, 0, 1, targetbuf) == 0;
+}
+/**
+* Removes and returns the first element of the list.
+*
+* Alias for cxListRemoveAndGetFirst().
+*
+* No destructor is called, and instead the element is copied to the
+* @p targetbuf which MUST be large enough to hold the removed element.
+* If the list is storing pointers, only the pointer is copied to @p targetbuf.
+*
+* @param list (@c CxList*) the list
+* @param targetbuf (@c void*) a buffer where to copy the element
+* @retval zero success
+* @retval non-zero list is empty
+* @see cxListRemoveAndGetFirst()
+* @see cxListPop()
+*/
+#define cxListPopFront(list, targetbuf) cxListRemoveAndGetFirst((list), (targetbuf))
+/**
+* Removes and returns the last element of the list.
+*
+* No destructor is called, and instead the element is copied to the
+* @p targetbuf which MUST be large enough to hold the removed element.
+* If the list is storing pointers, only the pointer is copied to @p targetbuf.
+*
+* @param list the list
+* @param targetbuf a buffer where to copy the element
+* @retval zero success
+* @retval non-zero list is empty
+*/
+cx_attr_nonnull
+cx_attr_access_w(2)
+static inline int cxListRemoveAndGetLast(
+CxList *list,
+void *targetbuf
+) {
+// note: index may wrap - member function will catch that
+return list->cl->remove(list, list->collection.size - 1, 1, targetbuf) == 0;
+}
+/**
+* Removes and returns the last element of the list.
+*
+* Alias for cxListRemoveAndGetLast().
+*
+* No destructor is called, and instead the element is copied to the
+* @p targetbuf which MUST be large enough to hold the removed element.
+* If the list is storing pointers, only the pointer is copied to @p targetbuf.
+*
+* @param list (@c CxList*) the list
+* @param targetbuf (@c void*) a buffer where to copy the element
+* @retval zero success
+* @retval non-zero list is empty
+* @see cxListRemoveAndGetLast()
+* @see cxListPopFront()
+*/
+#define cxListPop(list, targetbuf) cxListRemoveAndGetLast((list), (targetbuf))
+/**
 * 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
+* 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
 ) {
 return list->cl->remove(list, index, num, NULL);
 }
 /**
-* Removes and returns multiple element starting at the specified index.
+* Removes and returns multiple elements starting at the specified index.
 *
-* No destructor is called and instead the elements are copied to the
+* No destructor is called, and instead the elements are copied to the
 * @p targetbuf which MUST be large enough to hold all removed elements.
+* If the list is storing pointers, @p targetbuf is expected to be an array of pointers.
 *
 * @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
 }
 /**
 * Swaps two items in the list.
 *
-* Implementations should only allocate temporary memory for the swap, if
+* Implementations should only allocate temporary memory for the swap if
 * it is necessary.
 *
 * @param list the list
 * @param i the index of the first element
 * @param j the index of the second element
 * @retval zero success
-* @retval non-zero one of the indices is out of bounds
+* @retval non-zero one of the indices is out of bounds,
-* or the swap needed extra memory but allocation failed
+* or the swap needed extra memory, but allocation failed
 */
 cx_attr_nonnull
 static inline int cxListSwap(
 CxList *list,
 size_t i,
 return list->cl->swap(list, i, j);
 }
 /**
 * Returns a pointer to the element at the specified index.
+*
+* If the list is storing pointers, returns the pointer stored 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 list->cl->at(list, index);
 }
 /**
+* Returns a pointer to the first element.
+*
+* If the list is storing pointers, returns the first pointer stored in the list.
+*
+* @param list the list
+* @return a pointer to the first element or @c NULL if the list is empty
+*/
+cx_attr_nonnull
+static inline void *cxListFirst(const CxList *list) {
+return list->cl->at(list, 0);
+}
+/**
+* Returns a pointer to the last element.
+*
+* If the list is storing pointers, returns the last pointer stored in the list.
+*
+* @param list the list
+* @return a pointer to the last element or @c NULL if the list is empty
+*/
+cx_attr_nonnull
+static inline void *cxListLast(const CxList *list) {
+return list->cl->at(list, list->collection.size - 1);
+}
+/**
+* Sets the element at the specified index in the list
+*
+* @param list the list to set the element in
+* @param index the index to set the element at
+* @param elem element to set
+* @retval zero on success
+* @retval non-zero when index is out of bounds
+*/
+cx_attr_nonnull
+cx_attr_export
+int cxListSet(
+CxList *list,
+size_t index,
+const void *elem
+);
+/**
 * Returns an iterator pointing to the item at the specified index.
 *
 * The returned iterator is position-aware.
 *
-* If the index is out of range, a past-the-end iterator will be returned.
+* If the index is out of range or @p list is @c NULL, a past-the-end iterator will be returned.
 *
 * @param list the list
 * @param index the index where the iterator shall point at
 * @return a new iterator
 */
-cx_attr_nonnull
 cx_attr_nodiscard
 static inline CxIterator cxListIteratorAt(
 const CxList *list,
 size_t index
 ) {
+if (list == NULL) list = cxEmptyList;
 return list->cl->iterator(list, index, false);
 }
 /**
 * Returns a backwards iterator pointing to the item at the specified index.
 *
 * The returned iterator is position-aware.
 *
-* If the index is out of range, a past-the-end iterator will be returned.
+* If the index is out of range or @p list is @c NULL, a past-the-end iterator will be returned.
 *
 * @param list the list
 * @param index the index where the iterator shall point at
 * @return a new iterator
 */
-cx_attr_nonnull
 cx_attr_nodiscard
 static inline CxIterator cxListBackwardsIteratorAt(
 const CxList *list,
 size_t index
 ) {
+if (list == NULL) list = cxEmptyList;
 return list->cl->iterator(list, index, true);
 }
 /**
 * Returns a mutating iterator pointing to the item at the specified index.
 *
 * The returned iterator is position-aware.
 *
-* If the index is out of range, a past-the-end iterator will be returned.
+* If the index is out of range or @p list is @c NULL, a past-the-end iterator will be returned.
 *
 * @param list the list
 * @param index the index where the iterator shall point at
 * @return a new iterator
 */
-cx_attr_nonnull
 cx_attr_nodiscard
 cx_attr_export
 CxIterator cxListMutIteratorAt(
 CxList *list,
 size_t index
 * Returns a mutating backwards iterator pointing to the item at the
 * specified index.
 *
 * The returned iterator is position-aware.
 *
-* If the index is out of range, a past-the-end iterator will be returned.
+* If the index is out of range or @p list is @c NULL, a past-the-end iterator will be returned.
 *
 * @param list the list
 * @param index the index where the iterator shall point at
 * @return a new iterator
 */
-cx_attr_nonnull
 cx_attr_nodiscard
 cx_attr_export
 CxIterator cxListMutBackwardsIteratorAt(
 CxList *list,
 size_t index
 /**
 * Returns an iterator pointing to the first item of the list.
 *
 * The returned iterator is position-aware.
 *
-* If the list is empty, a past-the-end iterator will be returned.
+* If the list is empty or @c NULL, a past-the-end iterator will be returned.
 *
 * @param list the list
 * @return a new iterator
 */
-cx_attr_nonnull
 cx_attr_nodiscard
 static inline CxIterator cxListIterator(const CxList *list) {
+if (list == NULL) list = cxEmptyList;
 return list->cl->iterator(list, 0, false);
 }
 /**
 * Returns a mutating iterator pointing to the first item of the list.
 *
 * The returned iterator is position-aware.
 *
-* If the list is empty, a past-the-end iterator will be returned.
+* If the list is empty or @c NULL, a past-the-end iterator will be returned.
 *
 * @param list the list
 * @return a new iterator
 */
-cx_attr_nonnull
 cx_attr_nodiscard
 static inline CxIterator cxListMutIterator(CxList *list) {
+if (list == NULL) list = cxEmptyList;
 return cxListMutIteratorAt(list, 0);
 }
 /**
 * Returns a backwards iterator pointing to the last item of the list.
 *
 * The returned iterator is position-aware.
 *
-* If the list is empty, a past-the-end iterator will be returned.
+* If the list is empty or @c NULL, a past-the-end iterator will be returned.
 *
 * @param list the list
 * @return a new iterator
 */
-cx_attr_nonnull
 cx_attr_nodiscard
 static inline CxIterator cxListBackwardsIterator(const CxList *list) {
+if (list == NULL) list = cxEmptyList;
 return list->cl->iterator(list, list->collection.size - 1, true);
 }
 /**
 * Returns a mutating backwards iterator pointing to the last item of the list.
 *
 * The returned iterator is position-aware.
 *
-* If the list is empty, a past-the-end iterator will be returned.
+* If the list is empty or @c NULL, a past-the-end iterator will be returned.
 *
 * @param list the list
 * @return a new iterator
 */
-cx_attr_nonnull
 cx_attr_nodiscard
 static inline CxIterator cxListMutBackwardsIterator(CxList *list) {
+if (list == NULL) list = cxEmptyList;
 return cxListMutBackwardsIteratorAt(list, list->collection.size - 1);
 }
 /**
 * Returns the index of the first element that equals @p elem.
 *
 * @param list the list
 * @param elem the element to find
 * @return the index of the element or the size of the list when the element is not found
 * @see cxListIndexValid()
+* @see cxListContains()
 */
 cx_attr_nonnull
 cx_attr_nodiscard
 static inline size_t cxListFind(
 const CxList *list,
 ) {
 return list->cl->find_remove((CxList*)list, elem, false);
 }
 /**
+* Checks, if the list contains the specified element.
+*
+* The elements are compared with the list's comparator function.
+*
+* @param list the list
+* @param elem the element to find
+* @retval true if the element is contained
+* @retval false if the element is not contained
+* @see cxListFind()
+*/
+cx_attr_nonnull
+cx_attr_nodiscard
+static inline bool cxListContains(
+const CxList* list,
+const void* elem
+) {
+return list->cl->find_remove((CxList*)list, elem, false) < list->collection.size;
+}
+/**
 * Checks if the specified index is within bounds.
 *
 * @param list the list
 * @param index the index
 * @retval true if the index is within bounds
 *
 * @param list the list
 */
 cx_attr_nonnull
 static inline void cxListSort(CxList *list) {
+if (list->collection.sorted) return;
 list->cl->sort(list);
 list->collection.sorted = true;
 }
 /**
 * @param list the list which shall be freed
 */
 cx_attr_export
 void cxListFree(CxList *list);
-/**
-* 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.
-*/
-cx_attr_export
-extern CxList *const cxEmptyList;
 #ifdef __cplusplus
 } // extern "C"
 #endif

Mercurial > hg > dav / file comparison

comparison: ucx/cx/list.h

ucx/cx/list.h