Mercurial > hg > ucx / file diff

--- a/docs/Writerside/topics/compare.h.md	Fri Dec 19 17:24:18 2025 +0100
+++ b/docs/Writerside/topics/compare.h.md	Fri Dec 19 17:37:17 2025 +0100
@@ -2,10 +2,9 @@
 
 The `compare.h` header file contains a collection of compare functions for various primitive types.
 
-They come in three flavors:
+They come in two flavors:
 - prefixed with `cx_vcmp` they are taking the values directly as arguments
 - prefixed with `cx_cmp` the signature is designed to be compatible with the `cx_compare_func` function pointer type.
-- prefixed with `cx_ccmp` the signature is designed to be compatible with the `cx_compare_func2` function pointer type.
 
 ## Examples
 
@@ -31,13 +30,13 @@
 ```
 
 If you only have a `cx_compare_func` at hand but need to call a function that expects a `cx_compare_func2` and a `context`,
-you can use `cx_ccmp_wrap` and the `cx_compare_func_wrapper` struct to wrap your function.
+you can use `cx_cmp_wrap` and the `cx_compare_func_wrapper` struct to wrap your function.
 
 ```C
 void some_fun(int x, int y, cx_compare_func2 f, void *context);
 
 cx_compare_func_wrapper wrapper = {my_cmp_fun};
-some_fun(x, y, cx_ccmp_wrap, &wrapper);
+some_fun(x, y, cx_cmp_wrap, &wrapper);
 ```
 
 ## List of Functions
@@ -84,10 +83,32 @@
 int cx_cmp_uintptr(const void *a, const void *b);
 int cx_cmp_ulongint(const void *a, const void *b);
 int cx_cmp_ulonglong(const void *a, const void *b);
+```
 
-// Three-arguments Flavour
-int cx_ccmp_memcmp(const void *a, const void *b, void *size);
-int cx_ccmp_wrap(const void *a, const void *b, void *cmp_fun_wrapper);
+## Comparing with Context
+
+Sometimes it might be necessary to have some context available during the comparison.
+For this purpose, the `cx_compare_func2` specifies a signature with an additional `void*` argument.
+The [Collections](collection.h.md) API supports those functions via the `cxSetAdvancedCompareFunc()` macro.
+
+On the other hand, some API might provide _only_ the variant with three arguments,
+but you want to use one of the compare functions defined above.
+In this case, they can easily be wrapped 
+
+```C
+#include <cx/compare.h>
+
+typedef struct {
+    cx_compare_func cmp;
+} cx_compare_func_wrapper;
+
+// signature is cx_compare_func2 compatible
+int cx_cmp_wrap(const void *a, const void *b, void *wrapper);
+
+// example: imagine there is some_sort_fun()
+//          that only supports 3-argument compare functions
+cx_compare_func_wrapper wrapper = {cx_cmp_int};
+some_sort_fun(array, cx_cmp_wrap, &wrapper);
 ```
 
 <seealso>