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