ucx/ucx/utils.h

   1 /*
   2  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
   3  *
   4  * Copyright 2017 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 /**
  30  * @file utils.h
  31  *
  32  * Compare, copy and printf functions.
  33  *
  34  * @author Mike Becker
  35  * @author Olaf Wintermann
  36  */
  37
  38 #ifndef UCX_UTILS_H
  39 #define UCX_UTILS_H
  40
  41 #include "ucx.h"
  42 #include "string.h"
  43 #include "allocator.h"
  44 #include <inttypes.h>
  45 #include <string.h>
  46 #include <stdarg.h>
  47
  48 #ifdef __cplusplus
  49 extern "C" {
  50 #endif
  51
  52 /**
  53  * Default buffer size for ucx_stream_copy() and ucx_stream_ncopy().
  54  */
  55 #define UCX_STREAM_COPY_BUFSIZE 4096
  56
  57 /**
  58  * Copies a string.
  59  * @param s the string to copy
  60  * @param data omitted
  61  * @return a pointer to a copy of s1 that can be passed to free(void*)
  62  */
  63 void *ucx_strcpy(const void *s, void *data);
  64
  65 /**
  66  * Copies a memory area.
  67  * @param m a pointer to the memory area
  68  * @param n a pointer to the size_t containing the size of the memory area
  69  * @return a pointer to a copy of the specified memory area that can
  70  * be passed to free(void*)
  71  */
  72 void *ucx_memcpy(const void *m, void *n);
  73
  74
  75 /**
  76  * Reads data from a stream and writes it to another stream.
  77  *
  78  * @param src the source stream
  79  * @param dest the destination stream
  80  * @param rfnc the read function
  81  * @param wfnc the write function
  82  * @param buf a pointer to the copy buffer or <code>NULL</code> if a buffer
  83  * shall be implicitly created on the heap
  84  * @param bufsize the size of the copy buffer - if <code>NULL</code> was
  85  * provided for <code>buf</code>, this is the size of the buffer that shall be
  86  * implicitly created
  87  * @param n the maximum number of bytes that shall be copied
  88  * @return the total number of bytes copied
  89   */
  90 size_t ucx_stream_bncopy(void *src, void *dest, read_func rfnc, write_func wfnc,
  91         char* buf, size_t bufsize, size_t n);
  92
  93 /**
  94  * Shorthand for an unbounded ucx_stream_bncopy call using a default buffer.
  95  *
  96  * @param src the source stream
  97  * @param dest the destination stream
  98  * @param rfnc the read function
  99  * @param wfnc the write function
 100  * @return total number of bytes copied
 101  *
 102  * @see #UCX_STREAM_COPY_BUFSIZE
 103  */
 104 #define ucx_stream_copy(src,dest,rfnc,wfnc) ucx_stream_bncopy(\
 105         src, dest, (read_func)rfnc, (write_func)wfnc, \
 106         NULL, UCX_STREAM_COPY_BUFSIZE, (size_t)-1)
 107
 108 /**
 109  * Shorthand for ucx_stream_bncopy using a default copy buffer.
 110  *
 111  * @param src the source stream
 112  * @param dest the destination stream
 113  * @param rfnc the read function
 114  * @param wfnc the write function
 115  * @param n maximum number of bytes that shall be copied
 116  * @return total number of bytes copied
 117  */
 118 #define ucx_stream_ncopy(src,dest,rfnc,wfnc, n) ucx_stream_bncopy(\
 119         src, dest, (read_func)rfnc, (write_func)wfnc, \
 120         NULL, UCX_STREAM_COPY_BUFSIZE, n)
 121
 122 /**
 123  * Shorthand for an unbounded ucx_stream_bncopy call using the specified buffer.
 124  *
 125  * @param src the source stream
 126  * @param dest the destination stream
 127  * @param rfnc the read function
 128  * @param wfnc the write function
 129  * @param buf a pointer to the copy buffer or <code>NULL</code> if a buffer
 130  * shall be implicitly created on the heap
 131  * @param bufsize the size of the copy buffer - if <code>NULL</code> was
 132  * provided for <code>buf</code>, this is the size of the buffer that shall be
 133  * implicitly created
 134  * @return total number of bytes copied
 135  */
 136 #define ucx_stream_bcopy(src,dest,rfnc,wfnc, buf, bufsize) ucx_stream_bncopy(\
 137         src, dest, (read_func)rfnc, (write_func)wfnc, \
 138         buf, bufsize, (size_t)-1)
 139
 140 /**
 141  * Wraps the strcmp function.
 142  * @param s1 string one
 143  * @param s2 string two
 144  * @param data omitted
 145  * @return the result of strcmp(s1, s2)
 146  */
 147 int ucx_cmp_str(const void *s1, const void *s2, void *data);
 148
 149 /**
 150  * Wraps the strncmp function.
 151  * @param s1 string one
 152  * @param s2 string two
 153  * @param n a pointer to the size_t containing the third strncmp parameter
 154  * @return the result of strncmp(s1, s2, *n)
 155  */
 156 int ucx_cmp_strn(const void *s1, const void *s2, void *n);
 157
 158 /**
 159  * Wraps the sstrcmp function.
 160  * @param s1 sstr one
 161  * @param s2 sstr two
 162  * @param data ignored
 163  * @return the result of sstrcmp(s1, s2)
 164  */
 165 int ucx_cmp_sstr(const void *s1, const void *s2, void *data);
 166
 167 /**
 168  * Compares two integers of type int.
 169  * @param i1 pointer to integer one
 170  * @param i2 pointer to integer two
 171  * @param data omitted
 172  * @return -1, if *i1 is less than *i2, 0 if both are equal,
 173  * 1 if *i1 is greater than *i2
 174  */
 175 int ucx_cmp_int(const void *i1, const void *i2, void *data);
 176
 177 /**
 178  * Compares two integers of type long int.
 179  * @param i1 pointer to long integer one
 180  * @param i2 pointer to long integer two
 181  * @param data omitted
 182  * @return -1, if *i1 is less than *i2, 0 if both are equal,
 183  * 1 if *i1 is greater than *i2
 184  */
 185 int ucx_cmp_longint(const void *i1, const void *i2, void *data);
 186
 187 /**
 188  * Compares two integers of type long long.
 189  * @param i1 pointer to long long one
 190  * @param i2 pointer to long long two
 191  * @param data omitted
 192  * @return -1, if *i1 is less than *i2, 0 if both are equal,
 193  * 1 if *i1 is greater than *i2
 194  */
 195 int ucx_cmp_longlong(const void *i1, const void *i2, void *data);
 196
 197 /**
 198  * Compares two integers of type int16_t.
 199  * @param i1 pointer to int16_t one
 200  * @param i2 pointer to int16_t two
 201  * @param data omitted
 202  * @return -1, if *i1 is less than *i2, 0 if both are equal,
 203  * 1 if *i1 is greater than *i2
 204  */
 205 int ucx_cmp_int16(const void *i1, const void *i2, void *data);
 206
 207 /**
 208  * Compares two integers of type int32_t.
 209  * @param i1 pointer to int32_t one
 210  * @param i2 pointer to int32_t two
 211  * @param data omitted
 212  * @return -1, if *i1 is less than *i2, 0 if both are equal,
 213  * 1 if *i1 is greater than *i2
 214  */
 215 int ucx_cmp_int32(const void *i1, const void *i2, void *data);
 216
 217 /**
 218  * Compares two integers of type int64_t.
 219  * @param i1 pointer to int64_t one
 220  * @param i2 pointer to int64_t two
 221  * @param data omitted
 222  * @return -1, if *i1 is less than *i2, 0 if both are equal,
 223  * 1 if *i1 is greater than *i2
 224  */
 225 int ucx_cmp_int64(const void *i1, const void *i2, void *data);
 226
 227 /**
 228  * Compares two integers of type unsigned int.
 229  * @param i1 pointer to unsigned integer one
 230  * @param i2 pointer to unsigned integer two
 231  * @param data omitted
 232  * @return -1, if *i1 is less than *i2, 0 if both are equal,
 233  * 1 if *i1 is greater than *i2
 234  */
 235 int ucx_cmp_uint(const void *i1, const void *i2, void *data);
 236
 237 /**
 238  * Compares two integers of type unsigned long int.
 239  * @param i1 pointer to unsigned long integer one
 240  * @param i2 pointer to unsigned long integer two
 241  * @param data omitted
 242  * @return -1, if *i1 is less than *i2, 0 if both are equal,
 243  * 1 if *i1 is greater than *i2
 244  */
 245 int ucx_cmp_ulongint(const void *i1, const void *i2, void *data);
 246
 247 /**
 248  * Compares two integers of type unsigned long long.
 249  * @param i1 pointer to unsigned long long one
 250  * @param i2 pointer to unsigned long long two
 251  * @param data omitted
 252  * @return -1, if *i1 is less than *i2, 0 if both are equal,
 253  * 1 if *i1 is greater than *i2
 254  */
 255 int ucx_cmp_ulonglong(const void *i1, const void *i2, void *data);
 256
 257 /**
 258  * Compares two integers of type uint16_t.
 259  * @param i1 pointer to uint16_t one
 260  * @param i2 pointer to uint16_t two
 261  * @param data omitted
 262  * @return -1, if *i1 is less than *i2, 0 if both are equal,
 263  * 1 if *i1 is greater than *i2
 264  */
 265 int ucx_cmp_uint16(const void *i1, const void *i2, void *data);
 266
 267 /**
 268  * Compares two integers of type uint32_t.
 269  * @param i1 pointer to uint32_t one
 270  * @param i2 pointer to uint32_t two
 271  * @param data omitted
 272  * @return -1, if *i1 is less than *i2, 0 if both are equal,
 273  * 1 if *i1 is greater than *i2
 274  */
 275 int ucx_cmp_uint32(const void *i1, const void *i2, void *data);
 276
 277 /**
 278  * Compares two integers of type uint64_t.
 279  * @param i1 pointer to uint64_t one
 280  * @param i2 pointer to uint64_t two
 281  * @param data omitted
 282  * @return -1, if *i1 is less than *i2, 0 if both are equal,
 283  * 1 if *i1 is greater than *i2
 284  */
 285 int ucx_cmp_uint64(const void *i1, const void *i2, void *data);
 286
 287 /**
 288  * Distance function for integers of type int.
 289  * @param i1 pointer to integer one
 290  * @param i2 pointer to integer two
 291  * @param data omitted
 292  * @return i1 minus i2
 293  */
 294 intmax_t ucx_dist_int(const void *i1, const void *i2, void *data);
 295
 296 /**
 297  * Distance function for integers of type long int.
 298  * @param i1 pointer to long integer one
 299  * @param i2 pointer to long integer two
 300  * @param data omitted
 301  * @return i1 minus i2
 302  */
 303 intmax_t ucx_dist_longint(const void *i1, const void *i2, void *data);
 304
 305 /**
 306  * Distance function for integers of type long long.
 307  * @param i1 pointer to long long one
 308  * @param i2 pointer to long long two
 309  * @param data omitted
 310  * @return i1 minus i2
 311  */
 312 intmax_t ucx_dist_longlong(const void *i1, const void *i2, void *data);
 313
 314 /**
 315  * Distance function for integers of type int16_t.
 316  * @param i1 pointer to int16_t one
 317  * @param i2 pointer to int16_t two
 318  * @param data omitted
 319  * @return i1 minus i2
 320  */
 321 intmax_t ucx_dist_int16(const void *i1, const void *i2, void *data);
 322
 323 /**
 324  * Distance function for integers of type int32_t.
 325  * @param i1 pointer to int32_t one
 326  * @param i2 pointer to int32_t two
 327  * @param data omitted
 328  * @return i1 minus i2
 329  */
 330 intmax_t ucx_dist_int32(const void *i1, const void *i2, void *data);
 331
 332 /**
 333  * Distance function for integers of type int64_t.
 334  * @param i1 pointer to int64_t one
 335  * @param i2 pointer to int64_t two
 336  * @param data omitted
 337  * @return i1 minus i2
 338  */
 339 intmax_t ucx_dist_int64(const void *i1, const void *i2, void *data);
 340
 341 /**
 342  * Distance function for integers of type unsigned int.
 343  * @param i1 pointer to unsigned integer one
 344  * @param i2 pointer to unsigned integer two
 345  * @param data omitted
 346  * @return i1 minus i2
 347  */
 348 intmax_t ucx_dist_uint(const void *i1, const void *i2, void *data);
 349
 350 /**
 351  * Distance function for integers of type unsigned long int.
 352  * @param i1 pointer to unsigned long integer one
 353  * @param i2 pointer to unsigned long integer two
 354  * @param data omitted
 355  * @return i1 minus i2
 356  */
 357 intmax_t ucx_dist_ulongint(const void *i1, const void *i2, void *data);
 358
 359 /**
 360  * Distance function for integers of type unsigned long long.
 361  * @param i1 pointer to unsigned long long one
 362  * @param i2 pointer to unsigned long long two
 363  * @param data omitted
 364  * @return i1 minus i2
 365  */
 366 intmax_t ucx_dist_ulonglong(const void *i1, const void *i2, void *data);
 367
 368 /**
 369  * Distance function for integers of type uint16_t.
 370  * @param i1 pointer to uint16_t one
 371  * @param i2 pointer to uint16_t two
 372  * @param data omitted
 373  * @return i1 minus i2
 374  */
 375 intmax_t ucx_dist_uint16(const void *i1, const void *i2, void *data);
 376
 377 /**
 378  * Distance function for integers of type uint32_t.
 379  * @param i1 pointer to uint32_t one
 380  * @param i2 pointer to uint32_t two
 381  * @param data omitted
 382  * @return i1 minus i2
 383  */
 384 intmax_t ucx_dist_uint32(const void *i1, const void *i2, void *data);
 385
 386 /**
 387  * Distance function for integers of type uint64_t.
 388  * @param i1 pointer to uint64_t one
 389  * @param i2 pointer to uint64_t two
 390  * @param data omitted
 391  * @return i1 minus i2
 392  */
 393 intmax_t ucx_dist_uint64(const void *i1, const void *i2, void *data);
 394
 395 /**
 396  * Compares two real numbers of type float.
 397  * @param f1 pointer to float one
 398  * @param f2 pointer to float two
 399  * @param data if provided: a pointer to precision (default: 1e-6f)
 400  * @return -1, if *f1 is less than *f2, 0 if both are equal,
 401  * 1 if *f1 is greater than *f2
 402  */
 403
 404 int ucx_cmp_float(const void *f1, const void *f2, void *data);
 405
 406 /**
 407  * Compares two real numbers of type double.
 408  * @param d1 pointer to double one
 409  * @param d2 pointer to double two
 410  * @param data if provided: a pointer to precision (default: 1e-14)
 411  * @return -1, if *d1 is less than *d2, 0 if both are equal,
 412  * 1 if *d1 is greater than *d2
 413  */
 414 int ucx_cmp_double(const void *d1, const void *d2, void *data);
 415
 416 /**
 417  * Compares two pointers.
 418  * @param ptr1 pointer one
 419  * @param ptr2 pointer two
 420  * @param data omitted
 421  * @return -1 if ptr1 is less than ptr2, 0 if both are equal,
 422  * 1 if ptr1 is greater than ptr2
 423  */
 424 int ucx_cmp_ptr(const void *ptr1, const void *ptr2, void *data);
 425
 426 /**
 427  * Compares two memory areas.
 428  * @param ptr1 pointer one
 429  * @param ptr2 pointer two
 430  * @param n a pointer to the size_t containing the third parameter for memcmp
 431  * @return the result of memcmp(ptr1, ptr2, *n)
 432  */
 433 int ucx_cmp_mem(const void *ptr1, const void *ptr2, void *n);
 434
 435 /**
 436  * A <code>printf()</code> like function which writes the output to a stream by
 437  * using a write_func().
 438  * @param stream the stream the data is written to
 439  * @param wfc the write function
 440  * @param fmt format string
 441  * @param ... additional arguments
 442  * @return the total number of bytes written
 443  */
 444 int ucx_fprintf(void *stream, write_func wfc, const char *fmt, ...);
 445
 446 /**
 447  * <code>va_list</code> version of ucx_fprintf().
 448  * @param stream the stream the data is written to
 449  * @param wfc the write function
 450  * @param fmt format string
 451  * @param ap argument list
 452  * @return the total number of bytes written
 453  * @see ucx_fprintf()
 454  */
 455 int ucx_vfprintf(void *stream, write_func wfc, const char *fmt, va_list ap);
 456
 457 /**
 458  * A <code>printf()</code> like function which allocates space for a sstr_t
 459  * the result is written to.
 460  *
 461  * <b>Attention</b>: The sstr_t data is allocated with the allocators
 462  * ucx_allocator_malloc() function. So it is implementation dependent, if
 463  * the returned sstr_t.ptr pointer must be passed to the allocators
 464  * ucx_allocator_free() function manually.
 465  *
 466  * <b>Note</b>: The sstr_t.ptr of the return value will <i>always</i> be
 467  * <code>NULL</code>-terminated.
 468  *
 469  * @param allocator the UcxAllocator used for allocating the result sstr_t
 470  * @param fmt format string
 471  * @param ... additional arguments
 472  * @return a sstr_t containing the formatted string
 473  */
 474 sstr_t ucx_asprintf(UcxAllocator *allocator, const char *fmt, ...);
 475
 476 /**
 477  * <code>va_list</code> version of ucx_asprintf().
 478  *
 479  * @param allocator the UcxAllocator used for allocating the result sstr_t
 480  * @param fmt format string
 481  * @param ap argument list
 482  * @return a sstr_t containing the formatted string
 483  * @see ucx_asprintf()
 484  */
 485 sstr_t ucx_vasprintf(UcxAllocator *allocator, const char *fmt, va_list ap);
 486
 487 /** Shortcut for ucx_asprintf() with default allocator. */
 488 #define ucx_sprintf(...) \
 489     ucx_asprintf(ucx_default_allocator(), __VA_ARGS__)
 490
 491 /**
 492  * A <code>printf()</code> like function which writes the output to a
 493  * UcxBuffer.
 494  *
 495  * @param buffer the buffer the data is written to
 496  * @param ... format string and additional arguments
 497  * @return the total number of bytes written
 498  * @see ucx_fprintf()
 499  */
 500 #define ucx_bprintf(buffer, ...) ucx_fprintf((UcxBuffer*)buffer, \
 501         (write_func)ucx_buffer_write, __VA_ARGS__)
 502
 503 #ifdef __cplusplus
 504 }
 505 #endif
 506
 507 #endif /* UCX_UTILS_H */
 508