usr/src/lib/libcustr/common/libcustr.h

   1 /*
   2  * This file and its contents are supplied under the terms of the
   3  * Common Development and Distribution License ("CDDL"), version 1.0.
   4  * You may only use this file in accordance with the terms of version
   5  * 1.0 of the CDDL.
   6  *
   7  * A full copy of the text of the CDDL should have accompanied this
   8  * source.  A copy of the CDDL is also available via the Internet at
   9  * http://www.illumos.org/license/CDDL.
  10  */
  11
  12 /*
  13  * Copyright 2018, Joyent, Inc.
  14  */
  15
  16 #ifndef _LIBCUSTR_H
  17 #define _LIBCUSTR_H
  18
  19 #include <stdarg.h>
  20 #include <sys/types.h>
  21
  22 /* dynamic string utilities */
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 typedef struct custr custr_t;
  29
  30 /*
  31  * Allocate and free a "custr_t" dynamic string object.  Returns 0 on success
  32  * and -1 otherwise.
  33  */
  34 int custr_alloc(custr_t **);
  35 void custr_free(custr_t *);
  36
  37 /*
  38  * Allocate a "custr_t" dynamic string object that operates on a fixed external
  39  * buffer.
  40  */
  41 int custr_alloc_buf(custr_t **, void *, size_t);
  42
  43 /*
  44  * Append a single character, or a NUL-terminated string of characters, to a
  45  * dynamic string.  Returns 0 on success and -1 otherwise.  The dynamic string
  46  * will be unmodified if the function returns -1.
  47  */
  48 int custr_appendc(custr_t *, char);
  49 int custr_append(custr_t *, const char *);
  50
  51 /*
  52  * Append a format string and arguments as though the contents were being parsed
  53  * through snprintf. Returns 0 on success and -1 otherwise.  The dynamic string
  54  * will be unmodified if the function returns -1.
  55  */
  56 int custr_append_printf(custr_t *, const char *, ...);
  57 int custr_append_vprintf(custr_t *, const char *, va_list);
  58
  59 /*
  60  * Determine the length in bytes, not including the NUL terminator, of the
  61  * dynamic string.
  62  */
  63 size_t custr_len(custr_t *);
  64
  65 /*
  66  * Clear the contents of a dynamic string.  Does not free the underlying
  67  * memory.
  68  */
  69 void custr_reset(custr_t *);
  70
  71 /*
  72  * Retrieve a const pointer to a NUL-terminated string version of the contents
  73  * of the dynamic string.  Storage for this string should not be freed, and
  74  * the pointer will be invalidated by any mutations to the dynamic string.
  75  */
  76 const char *custr_cstr(custr_t *str);
  77
  78 #ifdef __cplusplus
  79 }
  80 #endif
  81
  82 #endif /* _LIBCUSTR_H */