stringbuilder: Functions for joining strings.
[ccan] / 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 */