comparison: docs/Writerside/topics/compare.h.md
docs/Writerside/topics/compare.h.md
- changeset 1634
- 006e076a8db7
- parent 1618
- ef7cab6eb131
equal
deleted
inserted
replaced
| 1633:fe24b68758bf | 1634:006e076a8db7 |
|---|---|
| 1 # Compare Functions | 1 # Compare Functions |
| 2 | 2 |
| 3 The `compare.h` header file contains a collection of compare functions for various primitive types. | 3 The `compare.h` header file contains a collection of compare functions for various primitive types. |
| 4 | 4 |
| 5 They come in three flavors: | 5 They come in two flavors: |
| 6 - prefixed with `cx_vcmp` they are taking the values directly as arguments | 6 - prefixed with `cx_vcmp` they are taking the values directly as arguments |
| 7 - prefixed with `cx_cmp` the signature is designed to be compatible with the `cx_compare_func` function pointer type. | 7 - prefixed with `cx_cmp` the signature is designed to be compatible with the `cx_compare_func` function pointer type. |
| 8 - prefixed with `cx_ccmp` the signature is designed to be compatible with the `cx_compare_func2` function pointer type. | |
| 9 | 8 |
| 10 ## Examples | 9 ## Examples |
| 11 | 10 |
| 12 In the following example we use `cx_cmp_int32` as compare function for a `CxList` of `int32_t` values. | 11 In the following example we use `cx_cmp_int32` as compare function for a `CxList` of `int32_t` values. |
| 13 | 12 |
| 29 // do something when equal (except tolerance) | 28 // do something when equal (except tolerance) |
| 30 } | 29 } |
| 31 ``` | 30 ``` |
| 32 | 31 |
| 33 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`, | 32 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`, |
| 34 you can use `cx_ccmp_wrap` and the `cx_compare_func_wrapper` struct to wrap your function. | 33 you can use `cx_cmp_wrap` and the `cx_compare_func_wrapper` struct to wrap your function. |
| 35 | 34 |
| 36 ```C | 35 ```C |
| 37 void some_fun(int x, int y, cx_compare_func2 f, void *context); | 36 void some_fun(int x, int y, cx_compare_func2 f, void *context); |
| 38 | 37 |
| 39 cx_compare_func_wrapper wrapper = {my_cmp_fun}; | 38 cx_compare_func_wrapper wrapper = {my_cmp_fun}; |
| 40 some_fun(x, y, cx_ccmp_wrap, &wrapper); | 39 some_fun(x, y, cx_cmp_wrap, &wrapper); |
| 41 ``` | 40 ``` |
| 42 | 41 |
| 43 ## List of Functions | 42 ## List of Functions |
| 44 | 43 |
| 45 ```C | 44 ```C |
| 82 int cx_cmp_uint64(const void *a, const void *b); | 81 int cx_cmp_uint64(const void *a, const void *b); |
| 83 int cx_cmp_size(const void *a, const void *b); | 82 int cx_cmp_size(const void *a, const void *b); |
| 84 int cx_cmp_uintptr(const void *a, const void *b); | 83 int cx_cmp_uintptr(const void *a, const void *b); |
| 85 int cx_cmp_ulongint(const void *a, const void *b); | 84 int cx_cmp_ulongint(const void *a, const void *b); |
| 86 int cx_cmp_ulonglong(const void *a, const void *b); | 85 int cx_cmp_ulonglong(const void *a, const void *b); |
| 86 ``` | |
| 87 | 87 |
| 88 // Three-arguments Flavour | 88 ## Comparing with Context |
| 89 int cx_ccmp_memcmp(const void *a, const void *b, void *size); | 89 |
| 90 int cx_ccmp_wrap(const void *a, const void *b, void *cmp_fun_wrapper); | 90 Sometimes it might be necessary to have some context available during the comparison. |
| 91 For this purpose, the `cx_compare_func2` specifies a signature with an additional `void*` argument. | |
| 92 The [Collections](collection.h.md) API supports those functions via the `cxSetAdvancedCompareFunc()` macro. | |
| 93 | |
| 94 On the other hand, some API might provide _only_ the variant with three arguments, | |
| 95 but you want to use one of the compare functions defined above. | |
| 96 In this case, they can easily be wrapped | |
| 97 | |
| 98 ```C | |
| 99 #include <cx/compare.h> | |
| 100 | |
| 101 typedef struct { | |
| 102 cx_compare_func cmp; | |
| 103 } cx_compare_func_wrapper; | |
| 104 | |
| 105 // signature is cx_compare_func2 compatible | |
| 106 int cx_cmp_wrap(const void *a, const void *b, void *wrapper); | |
| 107 | |
| 108 // example: imagine there is some_sort_fun() | |
| 109 // that only supports 3-argument compare functions | |
| 110 cx_compare_func_wrapper wrapper = {cx_cmp_int}; | |
| 111 some_sort_fun(array, cx_cmp_wrap, &wrapper); | |
| 91 ``` | 112 ``` |
| 92 | 113 |
| 93 <seealso> | 114 <seealso> |
| 94 <category ref="apidoc"> | 115 <category ref="apidoc"> |
| 95 <a href="https://ucx.sourceforge.io/api/compare_8h.html">compare.h</a> | 116 <a href="https://ucx.sourceforge.io/api/compare_8h.html">compare.h</a> |
