1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are met:
8 *
9 * 1. Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * 2. Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 * POSSIBILITY OF SUCH DAMAGE.
27 */
28 /**
29 * @file compare.h
30 * @brief A collection of simple compare functions.
31 * @author Mike Becker
32 * @author Olaf Wintermann
33 * @copyright 2-Clause BSD License
34 */
35
36 #ifndef UCX_COMPARE_H
37 #define UCX_COMPARE_H
38
39 #include "common.h"
40
41 #ifdef __cplusplus
42 extern "C" {
43 #endif
44
45 /**
46 * A comparator function comparing two arbitrary values.
47 *
48 * All functions from compare.h with the cx_cmp prefix are
49 * compatible with this signature and can be used as
50 * compare function for collections or other implementations
51 * that need to be type-agnostic.
52 *
53 * For simple comparisons the cx_vcmp family of functions
54 * can be used, but they are NOT compatible with this function
55 * pointer.
56 */
57 typedef int (*cx_compare_func)(const void *left, const void *right);
58
59 /**
60 * Compares two integers of type int.
61 *
62 * @note the parameters deliberately have type @c void* to be
63 * compatible with #cx_compare_func without the need of a cast.
64 *
65 * @param i1 pointer to integer one
66 * @param i2 pointer to integer two
67 * @retval -1 if the left argument is less than the right argument
68 * @retval 0 if both arguments are equal
69 * @retval 1 if the left argument is greater than the right argument
70 */
71 cx_attr_nonnull cx_attr_nodiscard
72 CX_EXPORT int cx_cmp_int(const void *i1, const void *i2);
73
74 /**
75 * Compares two integers of type int.
76 *
77 * @param i1 integer one
78 * @param i2 integer two
79 * @retval -1 if the left argument is less than the right argument
80 * @retval 0 if both arguments are equal
81 * @retval 1 if the left argument is greater than the right argument
82 */
83 cx_attr_nodiscard
84 CX_EXPORT int cx_vcmp_int(int i1, int i2);
85
86 /**
87 * Compares two integers of type long int.
88 *
89 * @note the parameters deliberately have type @c void* to be
90 * compatible with #cx_compare_func without the need of a cast.
91 *
92 * @param i1 pointer to long integer one
93 * @param i2 pointer to long integer two
94 * @retval -1 if the left argument is less than the right argument
95 * @retval 0 if both arguments are equal
96 * @retval 1 if the left argument is greater than the right argument
97 */
98 cx_attr_nonnull cx_attr_nodiscard
99 CX_EXPORT int cx_cmp_longint(const void *i1, const void *i2);
100
101 /**
102 * Compares two integers of type long int.
103 *
104 * @param i1 long integer one
105 * @param i2 long integer two
106 * @retval -1 if the left argument is less than the right argument
107 * @retval 0 if both arguments are equal
108 * @retval 1 if the left argument is greater than the right argument
109 */
110 cx_attr_nodiscard
111 CX_EXPORT int cx_vcmp_longint(long int i1, long int i2);
112
113 /**
114 * Compares two integers of type long long.
115 *
116 * @note the parameters deliberately have type @c void* to be
117 * compatible with #cx_compare_func without the need of a cast.
118 *
119 * @param i1 pointer to long long one
120 * @param i2 pointer to long long two
121 * @retval -1 if the left argument is less than the right argument
122 * @retval 0 if both arguments are equal
123 * @retval 1 if the left argument is greater than the right argument
124 */
125 cx_attr_nonnull cx_attr_nodiscard
126 CX_EXPORT int cx_cmp_longlong(const void *i1, const void *i2);
127
128 /**
129 * Compares two integers of type long long.
130 *
131 * @param i1 long long int one
132 * @param i2 long long int two
133 * @retval -1 if the left argument is less than the right argument
134 * @retval 0 if both arguments are equal
135 * @retval 1 if the left argument is greater than the right argument
136 */
137 cx_attr_nodiscard
138 CX_EXPORT int cx_vcmp_longlong(long long int i1, long long int i2);
139
140 /**
141 * Compares two integers of type int16_t.
142 *
143 * @note the parameters deliberately have type @c void* to be
144 * compatible with #cx_compare_func without the need of a cast.
145 *
146 * @param i1 pointer to int16_t one
147 * @param i2 pointer to int16_t two
148 * @retval -1 if the left argument is less than the right argument
149 * @retval 0 if both arguments are equal
150 * @retval 1 if the left argument is greater than the right argument
151 */
152 cx_attr_nonnull cx_attr_nodiscard
153 CX_EXPORT int cx_cmp_int16(const void *i1, const void *i2);
154
155 /**
156 * Compares two integers of type int16_t.
157 *
158 * @param i1 int16_t one
159 * @param i2 int16_t two
160 * @retval -1 if the left argument is less than the right argument
161 * @retval 0 if both arguments are equal
162 * @retval 1 if the left argument is greater than the right argument
163 */
164 cx_attr_nodiscard
165 CX_EXPORT int cx_vcmp_int16(int16_t i1, int16_t i2);
166
167 /**
168 * Compares two integers of type int32_t.
169 *
170 * @note the parameters deliberately have type @c void* to be
171 * compatible with #cx_compare_func without the need of a cast.
172 *
173 * @param i1 pointer to int32_t one
174 * @param i2 pointer to int32_t two
175 * @retval -1 if the left argument is less than the right argument
176 * @retval 0 if both arguments are equal
177 * @retval 1 if the left argument is greater than the right argument
178 */
179 cx_attr_nonnull cx_attr_nodiscard
180 CX_EXPORT int cx_cmp_int32(const void *i1, const void *i2);
181
182 /**
183 * Compares two integers of type int32_t.
184 *
185 * @param i1 int32_t one
186 * @param i2 int32_t two
187 * @retval -1 if the left argument is less than the right argument
188 * @retval 0 if both arguments are equal
189 * @retval 1 if the left argument is greater than the right argument
190 */
191 cx_attr_nodiscard
192 CX_EXPORT int cx_vcmp_int32(int32_t i1, int32_t i2);
193
194 /**
195 * Compares two integers of type int64_t.
196 *
197 * @note the parameters deliberately have type @c void* to be
198 * compatible with #cx_compare_func without the need of a cast.
199 *
200 * @param i1 pointer to int64_t one
201 * @param i2 pointer to int64_t two
202 * @retval -1 if the left argument is less than the right argument
203 * @retval 0 if both arguments are equal
204 * @retval 1 if the left argument is greater than the right argument
205 */
206 cx_attr_nonnull cx_attr_nodiscard
207 CX_EXPORT int cx_cmp_int64(const void *i1, const void *i2);
208
209 /**
210 * Compares two integers of type int64_t.
211 *
212 * @param i1 int64_t one
213 * @param i2 int64_t two
214 * @retval -1 if the left argument is less than the right argument
215 * @retval 0 if both arguments are equal
216 * @retval 1 if the left argument is greater than the right argument
217 */
218 cx_attr_nodiscard
219 CX_EXPORT int cx_vcmp_int64(int64_t i1, int64_t i2);
220
221 /**
222 * Compares two integers of type unsigned int.
223 *
224 * @note the parameters deliberately have type @c void* to be
225 * compatible with #cx_compare_func without the need of a cast.
226 *
227 * @param i1 pointer to unsigned integer one
228 * @param i2 pointer to unsigned integer two
229 * @retval -1 if the left argument is less than the right argument
230 * @retval 0 if both arguments are equal
231 * @retval 1 if the left argument is greater than the right argument
232 */
233 cx_attr_nonnull cx_attr_nodiscard
234 CX_EXPORT int cx_cmp_uint(const void *i1, const void *i2);
235
236 /**
237 * Compares two integers of type unsigned int.
238 *
239 * @param i1 unsigned integer one
240 * @param i2 unsigned integer two
241 * @retval -1 if the left argument is less than the right argument
242 * @retval 0 if both arguments are equal
243 * @retval 1 if the left argument is greater than the right argument
244 */
245 cx_attr_nodiscard
246 CX_EXPORT int cx_vcmp_uint(unsigned int i1, unsigned int i2);
247
248 /**
249 * Compares two integers of type unsigned long int.
250 *
251 * @note the parameters deliberately have type @c void* to be
252 * compatible with #cx_compare_func without the need of a cast.
253 *
254 * @param i1 pointer to unsigned long integer one
255 * @param i2 pointer to unsigned long integer two
256 * @retval -1 if the left argument is less than the right argument
257 * @retval 0 if both arguments are equal
258 * @retval 1 if the left argument is greater than the right argument
259 */
260 cx_attr_nonnull cx_attr_nodiscard
261 CX_EXPORT int cx_cmp_ulongint(const void *i1, const void *i2);
262
263 /**
264 * Compares two integers of type unsigned long int.
265 *
266 * @param i1 unsigned long integer one
267 * @param i2 unsigned long integer two
268 * @retval -1 if the left argument is less than the right argument
269 * @retval 0 if both arguments are equal
270 * @retval 1 if the left argument is greater than the right argument
271 */
272 cx_attr_nodiscard
273 CX_EXPORT int cx_vcmp_ulongint(unsigned long int i1, unsigned long int i2);
274
275 /**
276 * Compares two integers of type unsigned long long.
277 *
278 * @note the parameters deliberately have type @c void* to be
279 * compatible with #cx_compare_func without the need of a cast.
280 *
281 * @param i1 pointer to unsigned long long one
282 * @param i2 pointer to unsigned long long two
283 * @retval -1 if the left argument is less than the right argument
284 * @retval 0 if both arguments are equal
285 * @retval 1 if the left argument is greater than the right argument
286 */
287 cx_attr_nonnull cx_attr_nodiscard
288 CX_EXPORT int cx_cmp_ulonglong(const void *i1, const void *i2);
289
290 /**
291 * Compares two integers of type unsigned long long.
292 *
293 * @param i1 unsigned long long one
294 * @param i2 unsigned long long two
295 * @retval -1 if the left argument is less than the right argument
296 * @retval 0 if both arguments are equal
297 * @retval 1 if the left argument is greater than the right argument
298 */
299 cx_attr_nodiscard
300 CX_EXPORT int cx_vcmp_ulonglong(unsigned long long int i1, unsigned long long int i2);
301
302 /**
303 * Compares two integers of type uint16_t.
304 *
305 * @note the parameters deliberately have type @c void* to be
306 * compatible with #cx_compare_func without the need of a cast.
307 *
308 * @param i1 pointer to uint16_t one
309 * @param i2 pointer to uint16_t two
310 * @retval -1 if the left argument is less than the right argument
311 * @retval 0 if both arguments are equal
312 * @retval 1 if the left argument is greater than the right argument
313 */
314 cx_attr_nonnull cx_attr_nodiscard
315 CX_EXPORT int cx_cmp_uint16(const void *i1, const void *i2);
316
317 /**
318 * Compares two integers of type uint16_t.
319 *
320 * @param i1 uint16_t one
321 * @param i2 uint16_t two
322 * @retval -1 if the left argument is less than the right argument
323 * @retval 0 if both arguments are equal
324 * @retval 1 if the left argument is greater than the right argument
325 */
326 cx_attr_nodiscard
327 CX_EXPORT int cx_vcmp_uint16(uint16_t i1, uint16_t i2);
328
329 /**
330 * Compares two integers of type uint32_t.
331 *
332 * @note the parameters deliberately have type @c void* to be
333 * compatible with #cx_compare_func without the need of a cast.
334 *
335 * @param i1 pointer to uint32_t one
336 * @param i2 pointer to uint32_t two
337 * @retval -1 if the left argument is less than the right argument
338 * @retval 0 if both arguments are equal
339 * @retval 1 if the left argument is greater than the right argument
340 */
341 cx_attr_nonnull cx_attr_nodiscard
342 CX_EXPORT int cx_cmp_uint32(const void *i1, const void *i2);
343
344 /**
345 * Compares two integers of type uint32_t.
346 *
347 * @param i1 uint32_t one
348 * @param i2 uint32_t two
349 * @retval -1 if the left argument is less than the right argument
350 * @retval 0 if both arguments are equal
351 * @retval 1 if the left argument is greater than the right argument
352 */
353 cx_attr_nodiscard
354 CX_EXPORT int cx_vcmp_uint32(uint32_t i1, uint32_t i2);
355
356 /**
357 * Compares two integers of type uint64_t.
358 *
359 * @note the parameters deliberately have type @c void* to be
360 * compatible with #cx_compare_func without the need of a cast.
361 *
362 * @param i1 pointer to uint64_t one
363 * @param i2 pointer to uint64_t two
364 * @retval -1 if the left argument is less than the right argument
365 * @retval 0 if both arguments are equal
366 * @retval 1 if the left argument is greater than the right argument
367 */
368 cx_attr_nonnull cx_attr_nodiscard
369 CX_EXPORT int cx_cmp_uint64(const void *i1, const void *i2);
370
371 /**
372 * Compares two integers of type uint64_t.
373 *
374 * @param i1 uint64_t one
375 * @param i2 uint64_t two
376 * @retval -1 if the left argument is less than the right argument
377 * @retval 0 if both arguments are equal
378 * @retval 1 if the left argument is greater than the right argument
379 */
380 cx_attr_nodiscard
381 CX_EXPORT int cx_vcmp_uint64(uint64_t i1, uint64_t i2);
382
383 /**
384 * Compares two integers of type size_t.
385 *
386 * @note the parameters deliberately have type @c void* to be
387 * compatible with #cx_compare_func without the need of a cast.
388 *
389 * @param i1 pointer to size_t one
390 * @param i2 pointer to size_t two
391 * @retval -1 if the left argument is less than the right argument
392 * @retval 0 if both arguments are equal
393 * @retval 1 if the left argument is greater than the right argument
394 */
395 cx_attr_nonnull cx_attr_nodiscard
396 CX_EXPORT int cx_cmp_size(const void *i1, const void *i2);
397
398 /**
399 * Compares two integers of type size_t.
400 *
401 * @param i1 size_t one
402 * @param i2 size_t two
403 * @retval -1 if the left argument is less than the right argument
404 * @retval 0 if both arguments are equal
405 * @retval 1 if the left argument is greater than the right argument
406 */
407 cx_attr_nodiscard
408 CX_EXPORT int cx_vcmp_size(size_t i1, size_t i2);
409
410 /**
411 * Compares two real numbers of type float with precision 1e-6f.
412 *
413 * @note the parameters deliberately have type @c void* to be
414 * compatible with #cx_compare_func without the need of a cast.
415 *
416 * @param f1 pointer to float one
417 * @param f2 pointer to float two
418 * @retval -1 if the left argument is less than the right argument
419 * @retval 0 if both arguments are equal
420 * @retval 1 if the left argument is greater than the right argument
421 */
422 cx_attr_nonnull cx_attr_nodiscard
423 CX_EXPORT int cx_cmp_float(const void *f1, const void *f2);
424
425 /**
426 * Compares two real numbers of type float with precision 1e-6f.
427 *
428 * @param f1 float one
429 * @param f2 float two
430 * @retval -1 if the left argument is less than the right argument
431 * @retval 0 if both arguments are equal
432 * @retval 1 if the left argument is greater than the right argument
433 */
434 cx_attr_nodiscard
435 CX_EXPORT int cx_vcmp_float(float f1, float f2);
436
437 /**
438 * Compares two real numbers of type double with precision 1e-14.
439 *
440 * @note the parameters deliberately have type @c void* to be
441 * compatible with #cx_compare_func without the need of a cast.
442 *
443 * @param d1 pointer to double one
444 * @param d2 pointer to double two
445 * @retval -1 if the left argument is less than the right argument
446 * @retval 0 if both arguments are equal
447 * @retval 1 if the left argument is greater than the right argument
448 */
449 cx_attr_nonnull cx_attr_nodiscard
450 CX_EXPORT int cx_cmp_double(const void *d1, const void *d2);
451
452 /**
453 * Compares two real numbers of type double with precision 1e-14.
454 *
455 * @param d1 double one
456 * @param d2 double two
457 * @retval -1 if the left argument is less than the right argument
458 * @retval 0 if both arguments are equal
459 * @retval 1 if the left argument is greater than the right argument
460 */
461 cx_attr_nodiscard
462 CX_EXPORT int cx_vcmp_double(double d1, double d2);
463
464 /**
465 * Compares the integer representation of two pointers.
466 *
467 * @note the parameters deliberately have type @c void* to be
468 * compatible with #cx_compare_func without the need of a cast.
469 *
470 * @param ptr1 pointer to pointer one (const intptr_t*)
471 * @param ptr2 pointer to pointer two (const intptr_t*)
472 * @retval -1 if the left argument is less than the right argument
473 * @retval 0 if both arguments are equal
474 * @retval 1 if the left argument is greater than the right argument
475 */
476 cx_attr_nonnull cx_attr_nodiscard
477 CX_EXPORT int cx_cmp_intptr(const void *ptr1, const void *ptr2);
478
479 /**
480 * Compares the integer representation of two pointers.
481 *
482 * @param ptr1 pointer one
483 * @param ptr2 pointer two
484 * @retval -1 if the left argument is less than the right argument
485 * @retval 0 if both arguments are equal
486 * @retval 1 if the left argument is greater than the right argument
487 */
488 cx_attr_nodiscard
489 CX_EXPORT int cx_vcmp_intptr(intptr_t ptr1, intptr_t ptr2);
490
491 /**
492 * Compares the unsigned integer representation of two pointers.
493 *
494 * @note the parameters deliberately have type @c void* to be
495 * compatible with #cx_compare_func without the need of a cast.
496 *
497 * @param ptr1 pointer to pointer one (const uintptr_t*)
498 * @param ptr2 pointer to pointer two (const uintptr_t*)
499 * @retval -1 if the left argument is less than the right argument
500 * @retval 0 if both arguments are equal
501 * @retval 1 if the left argument is greater than the right argument
502 */
503 cx_attr_nonnull cx_attr_nodiscard
504 CX_EXPORT int cx_cmp_uintptr(const void *ptr1, const void *ptr2);
505
506 /**
507 * Compares the unsigned integer representation of two pointers.
508 *
509 * @param ptr1 pointer one
510 * @param ptr2 pointer two
511 * @retval -1 if the left argument is less than the right argument
512 * @retval 0 if both arguments are equal
513 * @retval 1 if the left argument is greater than the right argument
514 */
515 cx_attr_nodiscard
516 CX_EXPORT int cx_vcmp_uintptr(uintptr_t ptr1, uintptr_t ptr2);
517
518 /**
519 * Compares the pointers specified in the arguments without dereferencing.
520 *
521 * @param ptr1 pointer one
522 * @param ptr2 pointer two
523 * @retval -1 if the left argument is less than the right argument
524 * @retval 0 if both arguments are equal
525 * @retval 1 if the left argument is greater than the right argument
526 */
527 cx_attr_nonnull cx_attr_nodiscard
528 CX_EXPORT int cx_cmp_ptr(const void *ptr1, const void *ptr2);
529
530 #ifdef __cplusplus
531 } // extern "C"
532 #endif
533
534 #endif //UCX_COMPARE_H
535