docs/Writerside/topics/compare.h.md

# 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 allocator
    sizeof(int32_t),    // the size of one element
    256                 // reseve space for 256 elements
);
cxSetCompareFunc(list, cx_cmp_int32); // the compare function for the 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)
}
```

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_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_cmp_wrap, &wrapper);
```

## List of Functions

```C
#include <cx/compare.h>

// Value Flavour
int cx_vcmp_double(double a, double b);
int cx_vcmp_float(float a, float b);
int cx_vcmp_int(int a, int b);
int cx_vcmp_int16(int16_t a, int16_t b);
int cx_vcmp_int32(int32_t a, int32_t b));
int cx_vcmp_int64(int64_t a, int64_t b);
int cx_vcmp_intptr(intptr_t a, intptr_t b);
int cx_vcmp_longint(long int a, long int b);
int cx_vcmp_longlong(long long a, long long b);
int cx_vcmp_uint(unsigned int a, unsigned int b);
int cx_vcmp_uint16(uint16_t a, uint16_t b);
int cx_vcmp_uint32(uint32_t a, uint32_t b);
int cx_vcmp_uint64(uint64_t a, uint64_t b);
int cx_vcmp_size(size_t a, size_t b);
int cx_vcmp_uintptr(uintptr_t a, uintptr_t b);
int cx_vcmp_ulongint(unsigned long int a, unsigned long int b);
int cx_vcmp_ulonglong(unsigned long long a, unsigned long long b);

// Pointer Flavour
// (unspecified types make them compatible with cx_compare_func)
int cx_cmp_ptr(const void *a, const void *b);
int cx_cmp_double(const void *a, const void *b);
int cx_cmp_float(const void *a, const void *b);
int cx_cmp_int(const void *a, const void *b);
int cx_cmp_int16(const void *a, const void *b);
int cx_cmp_int32(const void *a, const void *b);
int cx_cmp_int64(const void *a, const void *b);
int cx_cmp_intptr(const void *a, const void *b);
int cx_cmp_longint(const void *a, const void *b);
int cx_cmp_longlong(const void *a, const void *b);
int cx_cmp_uint(const void *a, const void *b);
int cx_cmp_uint16(const void *a, const void *b);
int cx_cmp_uint32(const void *a, const void *b);
int cx_cmp_uint64(const void *a, const void *b);
int cx_cmp_size(const void *a, const void *b);
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);
```

## 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>
<category ref="apidoc">
<a href="https://ucx.sourceforge.io/api/compare_8h.html">compare.h</a>
</category>
</seealso>