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 */
83