ucx: comparison src/cx/list.h

-:25108c15e2d4
+:b4c3e0b4c3d5
 }
 /**
 * 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
 */
 size_t index
 ) {
 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

Mercurial > hg > ucx / file comparison

comparison: src/cx/list.h

src/cx/list.h