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 three 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

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_ccmp_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);
```

## 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);

// 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);
```

<seealso>
<category ref="apidoc">
<a href="https://ucx.sourceforge.io/api/compare_8h.html">compare.h</a>
</category>
</seealso>