Mercurial > hg > ucx / file diff

--- a/src/cx/list.h	Sun Jan 05 18:19:42 2025 +0100
+++ b/src/cx/list.h	Mon Jan 06 23:29:41 2025 +0100
@@ -280,50 +280,64 @@
 int cx_list_default_swap(struct cx_list_s *list, size_t i, size_t j);
 
 /**
+ * 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.
+ *
+ * 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
+ * the feature of storing pointers.
+ *
+ * @par Example
+ *
+ * @code
+ * CxList *myCustomListCreate(
+ *         const CxAllocator *allocator,
+ *         cx_compare_func comparator,
+ *         size_t elem_size
+ * ) {
+ *     if (allocator == NULL) {
+ *         allocator = cxDefaultAllocator;
+ *     }
+ *
+ *     MyCustomList *list = cxCalloc(allocator, 1, sizeof(MyCustomList));
+ *     if (list == NULL) return NULL;
+ *
+ *     // initialize
+ *     cx_list_init((CxList*)list, &my_custom_list_class,
+ *             allocator, comparator, elem_size);
+ *
+ *     // ... some more custom stuff ...
+ *
+ *     return (CxList *) list;
+ * }
+ * @endcode
+ *
+ * @param list the list to initialize
+ * @param cl the list class
+ * @param allocator the allocator for the elements
+ * @param comparator a compare function for the elements
+ * @param elem_size the size of one element
+ */
+cx_attr_nonnull_arg(1, 2, 3)
+void cx_list_init(
+    struct cx_list_s *list,
+    struct cx_list_class_s *cl,
+    const struct cx_allocator_s *allocator,
+    cx_compare_func comparator,
+    size_t elem_size
+);
+
+/**
  * Common type for all list implementations.
  */
 typedef struct cx_list_s CxList;
 
 /**
- * Advises the list to store copies of the objects (default mode of operation).
- *
- * Retrieving objects from this list will yield pointers to the copies stored
- * within this list.
- *
- * @param list the list
- * @see cxListStorePointers()
- */
-cx_attr_nonnull
-void cxListStoreObjects(CxList *list);
-
-/**
- * Advises the list to only store pointers to the objects.
- *
- * Retrieving objects from this list will yield the original pointers stored.
- *
- * @note This function forcibly sets the element size to the size of a pointer.
- * Invoking this function on a non-empty list that already stores copies of
- * objects is undefined.
- *
- * @param list the list
- * @see cxListStoreObjects()
- */
-cx_attr_nonnull
-void cxListStorePointers(CxList *list);
-
-/**
- * Returns true, if this list is storing pointers instead of the actual data.
- *
- * @param list
- * @return true, if this list is storing pointers
- * @see cxListStorePointers()
- */
-cx_attr_nonnull
-static inline bool cxListIsStoringPointers(const CxList *list) {
-    return list->collection.store_pointer;
-}
-
-/**
  * Returns the number of elements currently stored in the list.
  *
  * @param list the list