ucx: comparison src/cx/list.h

-:9a72258446cd
+:563033aa998c
 */
 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.
+* The data pointer may be @c NULL, in which case the function shall only allocate memory.
 * Returns a pointer to the allocated memory or @c NULL if allocation fails.
 */
 void *(*insert_element)(
 struct cx_list_s *list,
 size_t index,
 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, the comparison won't be optimized.
 */
 int (*compare)(
 const struct cx_list_s *list,
 const struct cx_list_s *other
 );
 /**
 * 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
+* You can use this as 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;
 /**
 * Initializes a list struct.
 *
 * Only use this function if you are creating your own list implementation.
 * The purpose of this function is to be called in the initialization code
-* of your list, to set certain members correctly.
+* of your list to set certain members correctly.
 *
 * This is particularly important when you want your list to support
 * #CX_STORE_POINTERS as @p elem_size. This function will wrap the list
 * class accordingly and make sure that you can implement your list as if
-* it was only storing objects and the wrapper will automatically enable
+* it was only storing objects, and the wrapper will automatically enable
 * the feature of storing pointers.
 *
 * @par Example
 *
 * @code
 * 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.
 *
-* 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 the @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
 * @retval zero success
 return list->cl->insert_unique(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 the @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.
 *
-* 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
 * 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.
 *
-* 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.
 *
 * If the list is not sorted already, the behavior is undefined.
 *
 * @param list the list
 * 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
+* @retval non-zero the list is empty
 * @see cxListPopFront()
 * @see cxListRemoveAndGetLast()
 */
 cx_attr_nonnull
 cx_attr_access_w(2)
 * 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
+* @retval non-zero the list is empty
 * @see cxListRemoveAndGetFirst()
 * @see cxListPop()
 */
 #define cxListPopFront(list, targetbuf) cxListRemoveAndGetFirst((list), (targetbuf))
 * 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
+* @retval non-zero the list is empty
 */
 cx_attr_nonnull
 cx_attr_access_w(2)
 static inline int cxListRemoveAndGetLast(
 CxList *list,
 * 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
+* @retval non-zero the list is empty
 * @see cxListRemoveAndGetLast()
 * @see cxListPopFront()
 */
 #define cxListPop(list, targetbuf) cxListRemoveAndGetLast((list), (targetbuf))
 ) {
 return list->cl->find_remove((CxList*)list, elem, false);
 }
 /**
-* Checks, if the list contains the specified element.
+* 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
 /**
 * Deallocates the memory of the specified list structure.
 *
 * Also calls the content destructor functions for each element, if specified.
 *
-* @param list the list which shall be freed
+* @param list the list that shall be freed
 */
 cx_attr_export
 void cxListFree(CxList *list);

Mercurial > hg > ucx / file comparison

comparison: src/cx/list.h

src/cx/list.h