Mercurial > hg > ucx / file diff

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/Writerside/topics/compare.h.md	Tue Feb 11 19:55:32 2025 +0100
@@ -0,0 +1,79 @@
+# Compare Functions
+
+The `compare.h` header file contains a collection of compare functions for various primitive types.
+
+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.
+
+## Examples
+
+In the following example we use `cx_cmp_int32` as compare function for a `CxList` of `int32_t` values.
+
+```C
+CxList *list = cxArrayListCreate(
+    cxDefaultAllocator, // use the default stdlib allocator
+    cx_cmp_int32,       // the compare function for the elements
+    sizeof(int32_t),    // the size of one element
+    256                 // reseve space for 256 elements
+);
+```
+
+In the next example we simply want to compare two `double` values with rounding tolerance.
+Note how the use of the `cx_vcmp` flavour makes it unnecessary to store the literal in a variable just to be able to take an address.
+```C
+double x = ...
+
+if (0 == cx_vcmp(x, 47.11)) {
+   // do something when equal (except tolerance)
+}
+```
+
+## List of Functions
+
+```C
+#include <cx/compare.h>
+
+// Value Flavour
+cx_vcmp_double
+cx_vcmp_float
+cx_vcmp_int
+cx_vcmp_int16
+cx_vcmp_int32
+cx_vcmp_int64
+cx_vcmp_intptr
+cx_vcmp_longint
+cx_vcmp_longlong
+cx_vcmp_uint
+cx_vcmp_uint16
+cx_vcmp_uint32
+cx_vcmp_uint64
+cx_vcmp_uintptr
+cx_vcmp_ulongint
+cx_vcmp_ulonglong
+
+// Pointer Flavour
+cx_cmp_double
+cx_cmp_float
+cx_cmp_int
+cx_cmp_int16
+cx_cmp_int32
+cx_cmp_int64
+cx_cmp_intptr
+cx_cmp_longint
+cx_cmp_longlong
+cx_cmp_ptr
+cx_cmp_uint
+cx_cmp_uint16
+cx_cmp_uint32
+cx_cmp_uint64
+cx_cmp_uintptr
+cx_cmp_ulongint
+cx_cmp_ulonglong
+```
+
+<seealso>
+<category ref="apidoc">
+<a href="https://ucx.sourceforge.io/api/compare_8h.html">compare.h</a>
+</category>
+</seealso>