talstr.h (7948B)
1 /* Licensed under BSD-MIT - see LICENSE file for details */ 2 #ifndef CCAN_STR_TAL_H 3 #define CCAN_STR_TAL_H 4 #ifdef TAL_USE_TALLOC 5 #include <ccan/tal/talloc/talloc.h> 6 #else 7 #include "tal.h" 8 #endif 9 #include <string.h> 10 #include <stdbool.h> 11 12 /** 13 * tal_strdup - duplicate a string 14 * @ctx: NULL, or tal allocated object to be parent. 15 * @p: the string to copy (can be take()). 16 * 17 * The returned string will have tal_count() == strlen() + 1. 18 */ 19 #define tal_strdup(ctx, p) tal_strdup_(ctx, p, TAL_LABEL(char, "[]")) 20 char *tal_strdup_(const tal_t *ctx, const char *p TAKES, const char *label); 21 22 /** 23 * tal_strndup - duplicate a limited amount of a string. 24 * @ctx: NULL, or tal allocated object to be parent. 25 * @p: the string to copy (can be take()). 26 * @n: the maximum length to copy. 27 * 28 * Always gives a nul-terminated string, with strlen() <= @n. 29 * The returned string will have tal_count() == strlen() + 1. 30 */ 31 #define tal_strndup(ctx, p, n) tal_strndup_(ctx, p, n, TAL_LABEL(char, "[]")) 32 char *tal_strndup_(const tal_t *ctx, const char *p TAKES, size_t n, 33 const char *label); 34 35 /** 36 * tal_fmt - allocate a formatted string 37 * @ctx: NULL, or tal allocated object to be parent. 38 * @fmt: the printf-style format (can be take()). 39 * 40 * The returned string will have tal_count() == strlen() + 1. 41 */ 42 #define tal_fmt(ctx, ...) \ 43 tal_fmt_(ctx, TAL_LABEL(char, "[]"), __VA_ARGS__) 44 char *tal_fmt_(const tal_t *ctx, const char *label, const char *fmt TAKES, 45 ...) PRINTF_FMT(3,4); 46 47 /** 48 * tal_vfmt - allocate a formatted string (va_list version) 49 * @ctx: NULL, or tal allocated object to be parent. 50 * @fmt: the printf-style format (can be take()). 51 * @va: the va_list containing the format args. 52 * 53 * The returned string will have tal_count() == strlen() + 1. 54 */ 55 #define tal_vfmt(ctx, fmt, va) \ 56 tal_vfmt_(ctx, fmt, va, TAL_LABEL(char, "[]")) 57 char *tal_vfmt_(const tal_t *ctx, const char *fmt TAKES, va_list ap, 58 const char *label) 59 PRINTF_FMT(2,0); 60 61 /** 62 * tal_append_fmt - append a formatted string to a talloc string. 63 * @baseptr: a pointer to the tal string to be appended to. 64 * @fmt: the printf-style format (can be take()). 65 * 66 * Returns false on allocation failure. 67 * Otherwise tal_count(*@baseptr) == strlen(*@baseptr) + 1. 68 */ 69 bool tal_append_fmt(char **baseptr, const char *fmt TAKES, ...) PRINTF_FMT(2,3); 70 71 /** 72 * tal_append_vfmt - append a formatted string to a talloc string (va_list) 73 * @baseptr: a pointer to the tal string to be appended to. 74 * @fmt: the printf-style format (can be take()). 75 * @va: the va_list containing the format args. 76 * 77 * Returns false on allocation failure. 78 * Otherwise tal_count(*@baseptr) == strlen(*@baseptr) + 1. 79 */ 80 bool tal_append_vfmt(char **baseptr, const char *fmt TAKES, va_list ap); 81 82 /** 83 * tal_strcat - join two strings together 84 * @ctx: NULL, or tal allocated object to be parent. 85 * @s1: the first string (can be take()). 86 * @s2: the second string (can be take()). 87 * 88 * The returned string will have tal_count() == strlen() + 1. 89 */ 90 #define tal_strcat(ctx, s1, s2) tal_strcat_(ctx, s1, s2, TAL_LABEL(char, "[]")) 91 char *tal_strcat_(const tal_t *ctx, const char *s1 TAKES, const char *s2 TAKES, 92 const char *label); 93 94 enum strsplit { 95 STR_EMPTY_OK, 96 STR_NO_EMPTY 97 }; 98 99 /** 100 * tal_strsplit - Split string into an array of substrings 101 * @ctx: the context to tal from (often NULL). 102 * @string: the string to split (can be take()). 103 * @delims: delimiters where lines should be split (can be take()). 104 * @flags: whether to include empty substrings. 105 * 106 * This function splits a single string into multiple strings. 107 * 108 * If @string is take(), the returned array will point into the 109 * mangled @string. 110 * 111 * Multiple delimiters result in empty substrings. By definition, no 112 * delimiters will appear in the substrings. 113 * 114 * The final char * in the array will be NULL, and tal_count() will 115 * return the number of elements plus 1 (for that NULL). 116 * 117 * Example: 118 * #include <ccan/tal/str/str.h> 119 * ... 120 * static unsigned int count_long_lines(const char *string) 121 * { 122 * char **lines; 123 * unsigned int i, long_lines = 0; 124 * 125 * // Can only fail on out-of-memory. 126 * lines = tal_strsplit(NULL, string, "\n", STR_NO_EMPTY); 127 * for (i = 0; lines[i] != NULL; i++) 128 * if (strlen(lines[i]) > 80) 129 * long_lines++; 130 * tal_free(lines); 131 * return long_lines; 132 * } 133 */ 134 #define tal_strsplit(ctx, string, delims, flag) \ 135 tal_strsplit_(ctx, string, delims, flag, TAL_LABEL(char *, "[]")) 136 char **tal_strsplit_(const tal_t *ctx, 137 const char *string TAKES, 138 const char *delims TAKES, 139 enum strsplit flag, 140 const char *label); 141 142 enum strjoin { 143 STR_TRAIL, 144 STR_NO_TRAIL 145 }; 146 147 /** 148 * tal_strjoin - Join an array of substrings into one long string 149 * @ctx: the context to tal from (often NULL). 150 * @strings: the NULL-terminated array of strings to join (can be take()) 151 * @delim: the delimiter to insert between the strings (can be take()) 152 * @flags: whether to add a delimieter to the end 153 * 154 * This function joins an array of strings into a single string. The 155 * return value is allocated using tal. Each string in @strings is 156 * followed by a copy of @delim. 157 * 158 * The returned string will have tal_count() == strlen() + 1. 159 * 160 * Example: 161 * // Append the string "--EOL" to each line. 162 * static char *append_to_all_lines(const char *string) 163 * { 164 * char **lines, *ret; 165 * 166 * lines = tal_strsplit(NULL, string, "\n", STR_EMPTY_OK); 167 * ret = tal_strjoin(NULL, lines, "-- EOL\n", STR_TRAIL); 168 * tal_free(lines); 169 * return ret; 170 * } 171 */ 172 #define tal_strjoin(ctx, strings, delim, flags) \ 173 tal_strjoin_(ctx, strings, delim, flags, TAL_LABEL(char, "[]")) 174 char *tal_strjoin_(const void *ctx, 175 char *strings[] TAKES, 176 const char *delim TAKES, 177 enum strjoin flags, 178 const char *label); 179 180 /** 181 * tal_strreg - match/extract from a string via (extended) regular expressions. 182 * @ctx: the context to tal from (often NULL) 183 * @string: the string to try to match (can be take()) 184 * @regex: the regular expression to match (can be take()) 185 * ...: pointers to strings to allocate for subexpressions. 186 * 187 * Returns true if we matched, in which case any parenthesized 188 * expressions in @regex are allocated and placed in the char ** 189 * arguments following @regex. NULL arguments mean the match is not 190 * saved. The order of the strings is the order 191 * of opening braces in the expression: in the case of repeated 192 * expressions (eg "([a-z])*") the last one is saved, in the case of 193 * non-existent matches (eg "([a-z]*)?") the pointer is set to NULL. 194 * 195 * Allocation failures or malformed regular expressions return false. 196 * The allocated strings will have tal_count() == strlen() + 1. 197 * 198 * See Also: 199 * regcomp(3), regex(3). 200 * 201 * Example: 202 * // Given "My name is Rusty" outputs "Hello Rusty!\n" 203 * // Given "my first name is Rusty Russell" outputs "Hello Rusty Russell!\n" 204 * // Given "My name isnt Rusty Russell" outputs "Hello there!\n" 205 * int main(int argc, char *argv[]) 206 * { 207 * char *person, *input; 208 * 209 * (void)argc; 210 * // Join args and trim trailing space. 211 * input = tal_strjoin(NULL, argv+1, " ", STR_NO_TRAIL); 212 * if (tal_strreg(NULL, input, 213 * "[Mm]y (first )?name is ([A-Za-z ]+)", 214 * NULL, &person)) 215 * printf("Hello %s!\n", person); 216 * else 217 * printf("Hello there!\n"); 218 * return 0; 219 * } 220 */ 221 #define tal_strreg(ctx, string, ...) \ 222 tal_strreg_(ctx, string, TAL_LABEL(char, "[]"), __VA_ARGS__) 223 bool tal_strreg_(const void *ctx, const char *string TAKES, 224 const char *label, const char *regex, ...); 225 #endif /* CCAN_STR_TAL_H */