git.ozlabs.org Git - ccan/blob - ccan/stringbuilder/stringbuilder.h

   1 /* CC0 (Public domain) - see LICENSE file for details */
   2 #ifndef CCAN_STRINGBUILDER_H
   3 #define CCAN_STRINGBUILDER_H
   4 #include "config.h"
   5 #include <stdarg.h>
   6 #include <sys/types.h>
   7
   8 /**
   9  * stringbuilder - Join strings from a varadic list.  The list of arguments
  10  * are all assumed to be of type const char*.  If the first argument is str,
  11  * then the contents of str are preserved and appended to.
  12  *
  13  * @str:        A pointer to a string buffer that will receive the result.
  14  * @str_sz:     Size of the buffer pointed to by str.
  15  * @delim:      A delimiter to separate the strings with, or NULL.
  16  *
  17  * Returns:     0 on success
  18  *              EMSGSIZE if the resulting string would overflow the buffer.
  19  *              If an overflow condition is detected, the buffer content is
  20  *              NOT defined.
  21  *
  22  * Example:
  23  *      int res;
  24  *      char file_name[80];
  25  *      res = stringbuilder(file_name, sizeof(file_name), "/",
  26  *              "/var/lib/foo", "bar", "baz");
  27  *      if (res)
  28  *              printf("Failed to determine file name: %s",
  29  *                      strerror(res));
  30  *      else
  31  *              printf("File is at %s", file_name);
  32  */
  33 #define stringbuilder(str, str_sz, delim, ...)  \
  34         stringbuilder_args(str, str_sz, delim, __VA_ARGS__, NULL)
  35 /**
  36  * stringbuilder_args - Join strings from a varadic list.  The list of
  37  * arguments are all assumed to be of type const char* and must end with a NULL.
  38  * If the first argument is str, then the contents of str are preserved and
  39  * appended to.
  40  *
  41  * @str:        A pointer to a string buffer that will receive the result.
  42  * @str_sz:     Size of the buffer pointed to by str.
  43  * @delim:      A delimiter to separate the strings with, or NULL.
  44  *
  45  * Returns:     0 on success
  46  *              EMSGSIZE if the resulting string would overflow the buffer.
  47  *              If an overflow condition is detected, the buffer content is
  48  *              NOT defined.
  49  *
  50  * Example:
  51  *      int res;
  52  *      char file_name[80];
  53  *      res = stringbuilder_args(file_name, sizeof(file_name), "/",
  54  *              "/var/lib/foo", "bar", "baz",
  55  *              NULL);
  56  *      if (res)
  57  *              printf("Failed to determine file name: %s",
  58  *                      strerror(res));
  59  *      else
  60  *              printf("File is at %s", file_name);
  61  */
  62 int stringbuilder_args(char* str, size_t str_sz, const char* delim, ...);
  63
  64 /**
  65  * stringbuilder_va - Join strings from a varadic list.  The list of arguments
  66  * are all assumed to be of type const char* and must end with a NULL.  If the
  67  * first argument is str, then the contents of str are preserved and appended
  68  * to.
  69  *
  70  * @str:        A pointer to a string buffer that will receive the result.
  71  * @str_sz:     Size of the buffer pointed to by str.
  72  * @delim:      A delimiter to separate the strings with, or NULL.
  73  *
  74  * Returns:     0 on success
  75  *              EMSGSIZE if the resulting string would overflow the buffer.
  76  *              If an overflow condition is detected, the buffer content is
  77  *              NOT defined.
  78  *
  79  * Example:
  80  *      #include <ccan/stringbuilder/stringbuilder.h>
  81  *      #include <stdarg.h>
  82  *      #include <stdio.h>
  83  *      #include <string.h>
  84  *      #include <errno.h>
  85  *
  86  *      int my_stringbuilder(char* str, size_t str_sz,
  87  *              const char* delim, ...);
  88  *
  89  *      int my_stringbuilder(char* str, size_t str_sz,
  90  *              const char* delim, ...)
  91  *      {
  92  *              int res;
  93  *              va_list ap;
  94  *              va_start(ap, delim);
  95  *              res = stringbuilder_va(str, str_sz, delim, ap);
  96  *              va_end(ap);
  97  *              return res;
  98  *      }
  99  *
 100  *      int main(void) {
 101  *              char my_string[80];
 102  *              int res = my_stringbuilder(my_string,
 103  *                      sizeof(my_string), " ", "foo", "bar", NULL);
 104  *              if (!res)
 105  *                      printf("%s\n", my_string);
 106  *              return res ? 1 : 0;
 107  *      }
 108  */
 109 int stringbuilder_va(char* str, size_t str_sz, const char* delim, va_list ap);
 110
 111 /**
 112  * stringbuilder_array - Join strings from an array of const char* pointers.
 113  *
 114  * @str:        A pointer to a string buffer that will receive the result.
 115  * @str_sz:     Size of the buffer pointed to by str.
 116  * @delim:      A delimiter to separate the strings with, or NULL.
 117  * @n_strings:  The number of strings to join.
 118  * @strings:    The array of strings to join.
 119  *
 120  * Returns:     0 on success
 121  *              EMSGSIZE if the resulting string would overflow the buffer.
 122  *              If an overflow condition is detected, the buffer content is
 123  *              NOT defined.
 124  *
 125  * Example:
 126  *      char my_args[128];
 127  *      int res = stringbuilder_array(my_args, sizeof(my_args), ", ",
 128  *              argc, (const char**)argv);
 129  *      if (res)
 130  *              printf("Failed to list arguments: %s",
 131  *                      strerror(res));
 132  *      else
 133  *              printf("My arguments were %s", my_args);
 134  */
 135 int stringbuilder_array(char* str, size_t str_sz, const char* delim,
 136                 size_t n_strings, const char** strings);
 137
 138 #endif /* CCAN_STRINGBUILDER_H */