Mercurial > hg > ucx / file diff

--- a/docs/Writerside/topics/collection.h.md	Fri Dec 19 18:31:26 2025 +0100
+++ b/docs/Writerside/topics/collection.h.md	Sat Dec 20 10:43:14 2025 +0100
@@ -60,10 +60,6 @@
 // the following two can be used to optimize loops
 cx_invoke_simple_compare_func(c, left, right) 
 cx_invoke_advanced_compare_func(c, left, right)
-
-// convenience macro for addressing and dereference elements in pointer collections
-cx_ref(c, elem) 
-cx_deref(c, elem) 
 ```
 
 If an advanced compare function is specified, `cx_invoke_compare_func()` will only invoke the advanced comparator.
@@ -77,7 +73,7 @@
 A typical use case would be this:
 
 ```C
-void *arg = // ... passed as argument, e.g. in cxListContains()
+void *arg = // ... passed as argument
 void *elem = // ... get a pointer to the element
 void *data;
 
@@ -88,11 +84,18 @@
     data = elem;
 }
 
-// ... or with the convenience macro
+// ... or with a convenience macro
 data = cx_deref(this_collection, elem);
 int result = cx_invoke_compare_func(this_collection, data, arg);
 ```
 
+> When you are implementing a custom `CxList`, the above handling of pointers vs. elements is implemented
+> by `cx_list_compare_wrapper`, a `cx_compare_func2` which takes the `list` as third argument.
+> It will do the dereferencing for you.
+> 
+> It is important that both arguments, left and right, for the compare function are either both pointers to pointers
+> or both pointers to elements, but never mixed.
+
 ## Destructor Functions
 
 For working with destructors, the following macros are defined:
@@ -121,6 +124,8 @@
 > If your collection is storing pointers (i.e. `cxCollectionStoresPointers()` returns `true`)
 > the `cx_invoke_destructor()` will make sure that the pointer to the element is dereferenced first,
 > so that the destructor functions are _always_ invoked with a pointer to the actual element.
+> 
+> This is different to how [comparator functions](#comparator-functions) work.
 {style="note"}
 
 <seealso>