]>
Commit | Line | Data |
---|---|---|
d1df5743 JH |
1 | #ifndef STRBUF_H |
2 | #define STRBUF_H | |
b449f4cf | 3 | |
45577796 CW |
4 | /* |
5 | * NOTE FOR STRBUF DEVELOPERS | |
6 | * | |
7 | * strbuf is a low-level primitive; as such it should interact only | |
8 | * with other low-level primitives. Do not introduce new functions | |
9 | * which interact with higher-level APIs. | |
10 | */ | |
11 | ||
f6f77559 EN |
12 | struct string_list; |
13 | ||
bdfdaa49 | 14 | /** |
97509a34 | 15 | * strbufs are meant to be used with all the usual C string and memory |
bdfdaa49 | 16 | * APIs. Given that the length of the buffer is known, it's often better to |
97509a34 | 17 | * use the mem* functions than a str* one (e.g., memchr vs. strchr). |
bdfdaa49 JK |
18 | * Though, one has to be careful about the fact that str* functions often |
19 | * stop on NULs and that strbufs may have embedded NULs. | |
20 | * | |
21 | * A strbuf is NUL terminated for convenience, but no function in the | |
22 | * strbuf API actually relies on the string being free of NULs. | |
23 | * | |
24 | * strbufs have some invariants that are very important to keep in mind: | |
25 | * | |
aa07cac4 | 26 | * - The `buf` member is never NULL, so it can be used in any usual C |
97509a34 | 27 | * string operations safely. strbufs _have_ to be initialized either by |
aa07cac4 | 28 | * `strbuf_init()` or by `= STRBUF_INIT` before the invariants, though. |
bdfdaa49 | 29 | * |
aa07cac4 JK |
30 | * Do *not* assume anything on what `buf` really is (e.g. if it is |
31 | * allocated memory or not), use `strbuf_detach()` to unwrap a memory | |
32 | * buffer from its strbuf shell in a safe way. That is the sole supported | |
33 | * way. This will give you a malloced buffer that you can later `free()`. | |
34 | * | |
35 | * However, it is totally safe to modify anything in the string pointed by | |
36 | * the `buf` member, between the indices `0` and `len-1` (inclusive). | |
37 | * | |
38 | * - The `buf` member is a byte array that has at least `len + 1` bytes | |
39 | * allocated. The extra byte is used to store a `'\0'`, allowing the | |
97509a34 | 40 | * `buf` member to be a valid C-string. All strbuf functions ensure this |
aa07cac4 JK |
41 | * invariant is preserved. |
42 | * | |
43 | * NOTE: It is OK to "play" with the buffer directly if you work it this | |
44 | * way: | |
45 | * | |
088c9a86 JK |
46 | * strbuf_grow(sb, SOME_SIZE); <1> |
47 | * strbuf_setlen(sb, sb->len + SOME_OTHER_SIZE); | |
48 | * | |
aa07cac4 JK |
49 | * <1> Here, the memory array starting at `sb->buf`, and of length |
50 | * `strbuf_avail(sb)` is all yours, and you can be sure that | |
51 | * `strbuf_avail(sb)` is at least `SOME_SIZE`. | |
52 | * | |
53 | * NOTE: `SOME_OTHER_SIZE` must be smaller or equal to `strbuf_avail(sb)`. | |
54 | * | |
55 | * Doing so is safe, though if it has to be done in many places, adding the | |
56 | * missing API to the strbuf module is the way to go. | |
57 | * | |
58 | * WARNING: Do _not_ assume that the area that is yours is of size `alloc | |
59 | * - 1` even if it's true in the current implementation. Alloc is somehow a | |
60 | * "private" member that should not be messed with. Use `strbuf_avail()` | |
61 | * instead. | |
62 | */ | |
b449f4cf | 63 | |
bdfdaa49 JK |
64 | /** |
65 | * Data Structures | |
66 | * --------------- | |
67 | */ | |
68 | ||
69 | /** | |
70 | * This is the string buffer structure. The `len` member can be used to | |
71 | * determine the current length of the string, and `buf` member provides | |
72 | * access to the string itself. | |
73 | */ | |
d1df5743 | 74 | struct strbuf { |
b449f4cf PH |
75 | size_t alloc; |
76 | size_t len; | |
bf0f910d | 77 | char *buf; |
d1df5743 JH |
78 | }; |
79 | ||
bdfdaa49 | 80 | extern char strbuf_slopbuf[]; |
608cfd31 | 81 | #define STRBUF_INIT { .buf = strbuf_slopbuf } |
b449f4cf | 82 | |
30e677e0 | 83 | struct object_id; |
84 | ||
bdfdaa49 | 85 | /** |
14e2177a JK |
86 | * Life Cycle Functions |
87 | * -------------------- | |
bdfdaa49 JK |
88 | */ |
89 | ||
90 | /** | |
91 | * Initialize the structure. The second parameter can be zero or a bigger | |
92 | * number to allocate memory, in case you want to prevent further reallocs. | |
93 | */ | |
c7e5fe79 | 94 | void strbuf_init(struct strbuf *sb, size_t alloc); |
bdfdaa49 JK |
95 | |
96 | /** | |
e0222159 JN |
97 | * Release a string buffer and the memory it used. After this call, the |
98 | * strbuf points to an empty string that does not need to be free()ed, as | |
99 | * if it had been set to `STRBUF_INIT` and never modified. | |
100 | * | |
101 | * To clear a strbuf in preparation for further use without the overhead | |
102 | * of free()ing and malloc()ing again, use strbuf_reset() instead. | |
bdfdaa49 | 103 | */ |
c7e5fe79 | 104 | void strbuf_release(struct strbuf *sb); |
bdfdaa49 JK |
105 | |
106 | /** | |
107 | * Detach the string from the strbuf and returns it; you now own the | |
108 | * storage the string occupies and it is your responsibility from then on | |
109 | * to release it with `free(3)` when you are done with it. | |
e0222159 JN |
110 | * |
111 | * The strbuf that previously held the string is reset to `STRBUF_INIT` so | |
112 | * it can be reused after calling this function. | |
bdfdaa49 | 113 | */ |
c7e5fe79 | 114 | char *strbuf_detach(struct strbuf *sb, size_t *sz); |
bdfdaa49 JK |
115 | |
116 | /** | |
117 | * Attach a string to a buffer. You should specify the string to attach, | |
118 | * the current length of the string and the amount of allocated memory. | |
119 | * The amount must be larger than the string length, because the string you | |
120 | * pass is supposed to be a NUL-terminated string. This string _must_ be | |
121 | * malloc()ed, and after attaching, the pointer cannot be relied upon | |
122 | * anymore, and neither be free()d directly. | |
123 | */ | |
c7e5fe79 | 124 | void strbuf_attach(struct strbuf *sb, void *str, size_t len, size_t mem); |
bdfdaa49 JK |
125 | |
126 | /** | |
127 | * Swap the contents of two string buffers. | |
128 | */ | |
187e290a NTND |
129 | static inline void strbuf_swap(struct strbuf *a, struct strbuf *b) |
130 | { | |
35d803bc | 131 | SWAP(*a, *b); |
c76689df | 132 | } |
b449f4cf | 133 | |
bdfdaa49 JK |
134 | |
135 | /** | |
14e2177a JK |
136 | * Functions related to the size of the buffer |
137 | * ------------------------------------------- | |
bdfdaa49 JK |
138 | */ |
139 | ||
140 | /** | |
141 | * Determine the amount of allocated but unused memory. | |
142 | */ | |
187e290a NTND |
143 | static inline size_t strbuf_avail(const struct strbuf *sb) |
144 | { | |
c76689df | 145 | return sb->alloc ? sb->alloc - sb->len - 1 : 0; |
b449f4cf | 146 | } |
a8f3e221 | 147 | |
bdfdaa49 JK |
148 | /** |
149 | * Ensure that at least this amount of unused memory is available after | |
150 | * `len`. This is used when you know a typical size for what you will add | |
151 | * and want to avoid repetitive automatic resizing of the underlying buffer. | |
152 | * This is never a needed operation, but can be critical for performance in | |
153 | * some cases. | |
154 | */ | |
c7e5fe79 | 155 | void strbuf_grow(struct strbuf *sb, size_t amount); |
a8f3e221 | 156 | |
bdfdaa49 JK |
157 | /** |
158 | * Set the length of the buffer to a given value. This function does *not* | |
159 | * allocate new memory, so you should not perform a `strbuf_setlen()` to a | |
160 | * length that is larger than `len + strbuf_avail()`. `strbuf_setlen()` is | |
161 | * just meant as a 'please fix invariants from this strbuf I just messed | |
162 | * with'. | |
163 | */ | |
187e290a NTND |
164 | static inline void strbuf_setlen(struct strbuf *sb, size_t len) |
165 | { | |
7141efab | 166 | if (len > (sb->alloc ? sb->alloc - 1 : 0)) |
46d699f4 | 167 | BUG("strbuf_setlen() beyond buffer"); |
c76689df | 168 | sb->len = len; |
65961d5a MÅ |
169 | if (sb->buf != strbuf_slopbuf) |
170 | sb->buf[len] = '\0'; | |
171 | else | |
172 | assert(!strbuf_slopbuf[0]); | |
b449f4cf | 173 | } |
bdfdaa49 JK |
174 | |
175 | /** | |
176 | * Empty the buffer by setting the size of it to zero. | |
177 | */ | |
b315c5c0 | 178 | #define strbuf_reset(sb) strbuf_setlen(sb, 0) |
b449f4cf | 179 | |
bdfdaa49 JK |
180 | |
181 | /** | |
14e2177a JK |
182 | * Functions related to the contents of the buffer |
183 | * ----------------------------------------------- | |
bdfdaa49 JK |
184 | */ |
185 | ||
186 | /** | |
d468fa27 JK |
187 | * Strip whitespace from the beginning (`ltrim`), end (`rtrim`), or both side |
188 | * (`trim`) of a string. | |
bdfdaa49 | 189 | */ |
c7e5fe79 SB |
190 | void strbuf_trim(struct strbuf *sb); |
191 | void strbuf_rtrim(struct strbuf *sb); | |
192 | void strbuf_ltrim(struct strbuf *sb); | |
bdfdaa49 | 193 | |
c64a8d20 | 194 | /* Strip trailing directory separators */ |
c7e5fe79 | 195 | void strbuf_trim_trailing_dir_sep(struct strbuf *sb); |
c64a8d20 | 196 | |
f9573628 | 197 | /* Strip trailing LF or CR/LF */ |
39f73315 | 198 | void strbuf_trim_trailing_newline(struct strbuf *sb); |
f9573628 | 199 | |
bdfdaa49 JK |
200 | /** |
201 | * Replace the contents of the strbuf with a reencoded form. Returns -1 | |
202 | * on error, 0 on success. | |
203 | */ | |
c7e5fe79 | 204 | int strbuf_reencode(struct strbuf *sb, const char *from, const char *to); |
bdfdaa49 JK |
205 | |
206 | /** | |
207 | * Lowercase each character in the buffer using `tolower`. | |
208 | */ | |
c7e5fe79 | 209 | void strbuf_tolower(struct strbuf *sb); |
bdfdaa49 JK |
210 | |
211 | /** | |
212 | * Compare two buffers. Returns an integer less than, equal to, or greater | |
213 | * than zero if the first buffer is found, respectively, to be less than, | |
214 | * to match, or be greater than the second buffer. | |
215 | */ | |
c7e5fe79 | 216 | int strbuf_cmp(const struct strbuf *first, const struct strbuf *second); |
eacd6dc5 | 217 | |
bdfdaa49 JK |
218 | |
219 | /** | |
14e2177a JK |
220 | * Adding data to the buffer |
221 | * ------------------------- | |
bdfdaa49 JK |
222 | * |
223 | * NOTE: All of the functions in this section will grow the buffer as | |
224 | * necessary. If they fail for some reason other than memory shortage and the | |
225 | * buffer hadn't been allocated before (i.e. the `struct strbuf` was set to | |
226 | * `STRBUF_INIT`), then they will free() it. | |
227 | */ | |
228 | ||
229 | /** | |
230 | * Add a single character to the buffer. | |
231 | */ | |
232 | static inline void strbuf_addch(struct strbuf *sb, int c) | |
233 | { | |
fec501da JK |
234 | if (!strbuf_avail(sb)) |
235 | strbuf_grow(sb, 1); | |
bdfdaa49 JK |
236 | sb->buf[sb->len++] = c; |
237 | sb->buf[sb->len] = '\0'; | |
238 | } | |
239 | ||
240 | /** | |
241 | * Add a character the specified number of times to the buffer. | |
242 | */ | |
c7e5fe79 | 243 | void strbuf_addchars(struct strbuf *sb, int c, size_t n); |
bdfdaa49 JK |
244 | |
245 | /** | |
246 | * Insert data to the given position of the buffer. The remaining contents | |
247 | * will be shifted, not overwritten. | |
248 | */ | |
c7e5fe79 | 249 | void strbuf_insert(struct strbuf *sb, size_t pos, const void *, size_t); |
bdfdaa49 | 250 | |
a91cc7fa RS |
251 | /** |
252 | * Insert a NUL-terminated string to the given position of the buffer. | |
253 | * The remaining contents will be shifted, not overwritten. It's an | |
254 | * inline function to allow the compiler to resolve strlen() calls on | |
255 | * constants at compile time. | |
256 | */ | |
257 | static inline void strbuf_insertstr(struct strbuf *sb, size_t pos, | |
258 | const char *s) | |
259 | { | |
260 | strbuf_insert(sb, pos, s, strlen(s)); | |
261 | } | |
262 | ||
5ef264db PSU |
263 | /** |
264 | * Insert data to the given position of the buffer giving a printf format | |
265 | * string. The contents will be shifted, not overwritten. | |
266 | */ | |
267 | void strbuf_vinsertf(struct strbuf *sb, size_t pos, const char *fmt, | |
268 | va_list ap); | |
269 | ||
75d31cee | 270 | __attribute__((format (printf, 3, 4))) |
5ef264db PSU |
271 | void strbuf_insertf(struct strbuf *sb, size_t pos, const char *fmt, ...); |
272 | ||
bdfdaa49 JK |
273 | /** |
274 | * Remove given amount of data from a given position of the buffer. | |
275 | */ | |
c7e5fe79 | 276 | void strbuf_remove(struct strbuf *sb, size_t pos, size_t len); |
bdfdaa49 JK |
277 | |
278 | /** | |
279 | * Remove the bytes between `pos..pos+len` and replace it with the given | |
280 | * data. | |
281 | */ | |
c7e5fe79 SB |
282 | void strbuf_splice(struct strbuf *sb, size_t pos, size_t len, |
283 | const void *data, size_t data_len); | |
bdfdaa49 JK |
284 | |
285 | /** | |
286 | * Add a NUL-terminated string to the buffer. Each line will be prepended | |
287 | * by a comment character and a blank. | |
288 | */ | |
c7e5fe79 | 289 | void strbuf_add_commented_lines(struct strbuf *out, |
787cb8a4 CW |
290 | const char *buf, size_t size, |
291 | char comment_line_char); | |
bdfdaa49 JK |
292 | |
293 | ||
294 | /** | |
295 | * Add data of given length to the buffer. | |
296 | */ | |
c7e5fe79 | 297 | void strbuf_add(struct strbuf *sb, const void *data, size_t len); |
bdfdaa49 JK |
298 | |
299 | /** | |
300 | * Add a NUL-terminated string to the buffer. | |
301 | * | |
302 | * NOTE: This function will *always* be implemented as an inline or a macro | |
303 | * using strlen, meaning that this is efficient to write things like: | |
304 | * | |
088c9a86 | 305 | * strbuf_addstr(sb, "immediate string"); |
bdfdaa49 JK |
306 | * |
307 | */ | |
308 | static inline void strbuf_addstr(struct strbuf *sb, const char *s) | |
309 | { | |
310 | strbuf_add(sb, s, strlen(s)); | |
311 | } | |
312 | ||
313 | /** | |
314 | * Copy the contents of another buffer at the end of the current one. | |
315 | */ | |
c7e5fe79 | 316 | void strbuf_addbuf(struct strbuf *sb, const struct strbuf *sb2); |
bdfdaa49 | 317 | |
e71c4a88 PSU |
318 | /** |
319 | * Join the arguments into a buffer. `delim` is put between every | |
320 | * two arguments. | |
321 | */ | |
322 | const char *strbuf_join_argv(struct strbuf *buf, int argc, | |
323 | const char **argv, char delim); | |
324 | ||
bdfdaa49 | 325 | /** |
6f1e2d52 RS |
326 | * Used with `strbuf_expand_step` to expand the literals %n and %x |
327 | * followed by two hexadecimal digits. Returns the number of recognized | |
4416b86c | 328 | * characters. |
bdfdaa49 | 329 | */ |
4416b86c | 330 | size_t strbuf_expand_literal(struct strbuf *sb, const char *placeholder); |
bdfdaa49 | 331 | |
fd2015b3 | 332 | /** |
44ccb337 RS |
333 | * If the string pointed to by `formatp` contains a percent sign ("%"), |
334 | * advance it to point to the character following the next one and | |
335 | * return 1, otherwise return 0. Append the substring before that | |
336 | * percent sign to `sb`, or the whole string if there is none. | |
fd2015b3 | 337 | */ |
44ccb337 | 338 | int strbuf_expand_step(struct strbuf *sb, const char **formatp); |
bdfdaa49 JK |
339 | |
340 | /** | |
341 | * Append the contents of one strbuf to another, quoting any | |
342 | * percent signs ("%") into double-percents ("%%") in the | |
343 | * destination. This is useful for literal data to be fed to either | |
344 | * strbuf_expand or to the *printf family of functions. | |
345 | */ | |
c7e5fe79 | 346 | void strbuf_addbuf_percentquote(struct strbuf *dst, const struct strbuf *src); |
bdfdaa49 | 347 | |
b44d0118 | 348 | #define STRBUF_ENCODE_SLASH 1 |
349 | ||
46fd7b39 | 350 | /** |
351 | * Append the contents of a string to a strbuf, percent-encoding any characters | |
352 | * that are needed to be encoded for a URL. | |
b44d0118 | 353 | * |
354 | * If STRBUF_ENCODE_SLASH is set in flags, percent-encode slashes. Otherwise, | |
355 | * slashes are not percent-encoded. | |
46fd7b39 | 356 | */ |
b44d0118 | 357 | void strbuf_add_percentencode(struct strbuf *dst, const char *src, int flags); |
46fd7b39 | 358 | |
bdfdaa49 JK |
359 | /** |
360 | * Append the given byte size as a human-readable string (i.e. 12.23 KiB, | |
361 | * 3.50 MiB). | |
362 | */ | |
c7e5fe79 | 363 | void strbuf_humanise_bytes(struct strbuf *buf, off_t bytes); |
bdfdaa49 | 364 | |
8f354a1f DR |
365 | /** |
366 | * Append the given byte rate as a human-readable string (i.e. 12.23 KiB/s, | |
367 | * 3.50 MiB/s). | |
368 | */ | |
369 | void strbuf_humanise_rate(struct strbuf *buf, off_t bytes); | |
370 | ||
bdfdaa49 JK |
371 | /** |
372 | * Add a formatted string to the buffer. | |
373 | */ | |
374 | __attribute__((format (printf,2,3))) | |
c7e5fe79 | 375 | void strbuf_addf(struct strbuf *sb, const char *fmt, ...); |
bdfdaa49 JK |
376 | |
377 | /** | |
378 | * Add a formatted string prepended by a comment character and a | |
379 | * blank to the buffer. | |
380 | */ | |
787cb8a4 CW |
381 | __attribute__((format (printf, 3, 4))) |
382 | void strbuf_commented_addf(struct strbuf *sb, char comment_line_char, const char *fmt, ...); | |
bdfdaa49 JK |
383 | |
384 | __attribute__((format (printf,2,0))) | |
c7e5fe79 | 385 | void strbuf_vaddf(struct strbuf *sb, const char *fmt, va_list ap); |
bdfdaa49 | 386 | |
aa1462cc JK |
387 | /** |
388 | * Add the time specified by `tm`, as formatted by `strftime`. | |
c3fbf81a RS |
389 | * `tz_offset` is in decimal hhmm format, e.g. -600 means six hours west |
390 | * of Greenwich, and it's used to expand %z internally. However, tokens | |
391 | * with modifiers (e.g. %Ez) are passed to `strftime`. | |
3b702239 ÆAB |
392 | * `suppress_tz_name`, when set, expands %Z internally to the empty |
393 | * string rather than passing it to `strftime`. | |
c3fbf81a | 394 | */ |
c7e5fe79 SB |
395 | void strbuf_addftime(struct strbuf *sb, const char *fmt, |
396 | const struct tm *tm, int tz_offset, | |
397 | int suppress_tz_name); | |
aa1462cc | 398 | |
bdfdaa49 JK |
399 | /** |
400 | * Read a given size of data from a FILE* pointer to the buffer. | |
401 | * | |
402 | * NOTE: The buffer is rewound if the read fails. If -1 is returned, | |
403 | * `errno` must be consulted, like you would do for `read(3)`. | |
1a0c8dfd JH |
404 | * `strbuf_read()`, `strbuf_read_file()` and `strbuf_getline_*()` |
405 | * family of functions have the same behaviour as well. | |
bdfdaa49 | 406 | */ |
c7e5fe79 | 407 | size_t strbuf_fread(struct strbuf *sb, size_t size, FILE *file); |
bdfdaa49 JK |
408 | |
409 | /** | |
410 | * Read the contents of a given file descriptor. The third argument can be | |
411 | * used to give a hint about the file size, to avoid reallocs. If read fails, | |
412 | * any partial read is undone. | |
413 | */ | |
c7e5fe79 | 414 | ssize_t strbuf_read(struct strbuf *sb, int fd, size_t hint); |
bdfdaa49 | 415 | |
b4e04fb6 SB |
416 | /** |
417 | * Read the contents of a given file descriptor partially by using only one | |
418 | * attempt of xread. The third argument can be used to give a hint about the | |
419 | * file size, to avoid reallocs. Returns the number of new bytes appended to | |
420 | * the sb. | |
421 | */ | |
c7e5fe79 | 422 | ssize_t strbuf_read_once(struct strbuf *sb, int fd, size_t hint); |
b4e04fb6 | 423 | |
bdfdaa49 JK |
424 | /** |
425 | * Read the contents of a file, specified by its path. The third argument | |
426 | * can be used to give a hint about the file size, to avoid reallocs. | |
ed008d7b PB |
427 | * Return the number of bytes read or a negative value if some error |
428 | * occurred while opening or reading the file. | |
bdfdaa49 | 429 | */ |
c7e5fe79 | 430 | ssize_t strbuf_read_file(struct strbuf *sb, const char *path, size_t hint); |
bdfdaa49 JK |
431 | |
432 | /** | |
433 | * Read the target of a symbolic link, specified by its path. The third | |
434 | * argument can be used to give a hint about the size, to avoid reallocs. | |
435 | */ | |
c7e5fe79 | 436 | int strbuf_readlink(struct strbuf *sb, const char *path, size_t hint); |
bdfdaa49 | 437 | |
2dac9b56 SB |
438 | /** |
439 | * Write the whole content of the strbuf to the stream not stopping at | |
440 | * NUL bytes. | |
441 | */ | |
c7e5fe79 | 442 | ssize_t strbuf_write(struct strbuf *sb, FILE *stream); |
2dac9b56 | 443 | |
af35e56b PS |
444 | /** |
445 | * Read from a FILE * until the specified terminator is encountered, | |
446 | * overwriting the existing contents of the strbuf. | |
447 | * | |
448 | * Reading stops after the terminator or at EOF. The terminator is | |
449 | * removed from the buffer before returning. If the terminator is LF | |
450 | * and if it is preceded by a CR, then the whole CRLF is stripped. | |
451 | * Returns 0 unless there was nothing left before EOF, in which case | |
452 | * it returns `EOF`. | |
453 | */ | |
454 | int strbuf_getdelim_strip_crlf(struct strbuf *sb, FILE *fp, int term); | |
455 | ||
bdfdaa49 | 456 | /** |
1a0c8dfd JH |
457 | * Read a line from a FILE *, overwriting the existing contents of |
458 | * the strbuf. The strbuf_getline*() family of functions share | |
459 | * this signature, but have different line termination conventions. | |
460 | * | |
bdfdaa49 JK |
461 | * Reading stops after the terminator or at EOF. The terminator |
462 | * is removed from the buffer before returning. Returns 0 unless | |
463 | * there was nothing left before EOF, in which case it returns `EOF`. | |
464 | */ | |
8f309aeb JH |
465 | typedef int (*strbuf_getline_fn)(struct strbuf *, FILE *); |
466 | ||
467 | /* Uses LF as the line terminator */ | |
c7e5fe79 | 468 | int strbuf_getline_lf(struct strbuf *sb, FILE *fp); |
8f309aeb JH |
469 | |
470 | /* Uses NUL as the line terminator */ | |
c7e5fe79 | 471 | int strbuf_getline_nul(struct strbuf *sb, FILE *fp); |
8f309aeb | 472 | |
c8aa9fdf | 473 | /* |
8f309aeb JH |
474 | * Similar to strbuf_getline_lf(), but additionally treats a CR that |
475 | * comes immediately before the LF as part of the terminator. | |
1a0c8dfd JH |
476 | * This is the most friendly version to be used to read "text" files |
477 | * that can come from platforms whose native text format is CRLF | |
478 | * terminated. | |
c8aa9fdf | 479 | */ |
c7e5fe79 | 480 | int strbuf_getline(struct strbuf *sb, FILE *file); |
c8aa9fdf | 481 | |
bdfdaa49 JK |
482 | |
483 | /** | |
484 | * Like `strbuf_getline`, but keeps the trailing terminator (if | |
485 | * any) in the buffer. | |
486 | */ | |
c7e5fe79 | 487 | int strbuf_getwholeline(struct strbuf *sb, FILE *file, int term); |
bdfdaa49 | 488 | |
bd021f39 PS |
489 | /** |
490 | * Like `strbuf_getwholeline`, but appends the line instead of | |
491 | * resetting the buffer first. | |
492 | */ | |
493 | int strbuf_appendwholeline(struct strbuf *sb, FILE *file, int term); | |
494 | ||
bdfdaa49 JK |
495 | /** |
496 | * Like `strbuf_getwholeline`, but operates on a file descriptor. | |
497 | * It reads one character at a time, so it is very slow. Do not | |
498 | * use it unless you need the correct position in the file | |
499 | * descriptor. | |
500 | */ | |
c7e5fe79 | 501 | int strbuf_getwholeline_fd(struct strbuf *sb, int fd, int term); |
bdfdaa49 JK |
502 | |
503 | /** | |
504 | * Set the buffer to the path of the current working directory. | |
505 | */ | |
c7e5fe79 | 506 | int strbuf_getcwd(struct strbuf *sb); |
bdfdaa49 | 507 | |
670c359d JK |
508 | /** |
509 | * Normalize in-place the path contained in the strbuf. See | |
510 | * normalize_path_copy() for details. If an error occurs, the contents of "sb" | |
511 | * are left untouched, and -1 is returned. | |
512 | */ | |
c7e5fe79 | 513 | int strbuf_normalize_path(struct strbuf *sb); |
670c359d | 514 | |
bdfdaa49 | 515 | /** |
787cb8a4 CW |
516 | * Strip whitespace from a buffer. If comment_line_char is non-NUL, |
517 | * then lines beginning with that character are considered comments, | |
518 | * thus removed. | |
bdfdaa49 | 519 | */ |
787cb8a4 | 520 | void strbuf_stripspace(struct strbuf *buf, char comment_line_char); |
63af4a84 | 521 | |
6dda4e60 JK |
522 | static inline int strbuf_strip_suffix(struct strbuf *sb, const char *suffix) |
523 | { | |
524 | if (strip_suffix_mem(sb->buf, &sb->len, suffix)) { | |
525 | strbuf_setlen(sb, sb->len); | |
526 | return 1; | |
527 | } else | |
528 | return 0; | |
529 | } | |
530 | ||
6afbbdda | 531 | /** |
06379a65 MH |
532 | * Split str (of length slen) at the specified terminator character. |
533 | * Return a null-terminated array of pointers to strbuf objects | |
534 | * holding the substrings. The substrings include the terminator, | |
535 | * except for the last substring, which might be unterminated if the | |
536 | * original string did not end with a terminator. If max is positive, | |
537 | * then split the string into at most max substrings (with the last | |
538 | * substring containing everything following the (max-1)th terminator | |
539 | * character). | |
540 | * | |
f20e56e2 JK |
541 | * The most generic form is `strbuf_split_buf`, which takes an arbitrary |
542 | * pointer/len buffer. The `_str` variant takes a NUL-terminated string, | |
543 | * the `_max` variant takes a strbuf, and just `strbuf_split` is a convenience | |
544 | * wrapper to drop the `max` parameter. | |
545 | * | |
06379a65 MH |
546 | * For lighter-weight alternatives, see string_list_split() and |
547 | * string_list_split_in_place(). | |
548 | */ | |
c7e5fe79 SB |
549 | struct strbuf **strbuf_split_buf(const char *str, size_t len, |
550 | int terminator, int max); | |
06379a65 | 551 | |
2f1d9e2b | 552 | static inline struct strbuf **strbuf_split_str(const char *str, |
17b73dc6 | 553 | int terminator, int max) |
2f1d9e2b | 554 | { |
17b73dc6 | 555 | return strbuf_split_buf(str, strlen(str), terminator, max); |
2f1d9e2b | 556 | } |
06379a65 | 557 | |
2f1d9e2b | 558 | static inline struct strbuf **strbuf_split_max(const struct strbuf *sb, |
c7e5fe79 | 559 | int terminator, int max) |
2f1d9e2b | 560 | { |
17b73dc6 | 561 | return strbuf_split_buf(sb->buf, sb->len, terminator, max); |
2f1d9e2b | 562 | } |
06379a65 | 563 | |
17b73dc6 MH |
564 | static inline struct strbuf **strbuf_split(const struct strbuf *sb, |
565 | int terminator) | |
28fc3a68 | 566 | { |
17b73dc6 | 567 | return strbuf_split_max(sb, terminator, 0); |
28fc3a68 | 568 | } |
06379a65 | 569 | |
f6f77559 EN |
570 | /* |
571 | * Adds all strings of a string list to the strbuf, separated by the given | |
572 | * separator. For example, if sep is | |
573 | * ', ' | |
574 | * and slist contains | |
575 | * ['element1', 'element2', ..., 'elementN'], | |
576 | * then write: | |
577 | * 'element1, element2, ..., elementN' | |
578 | * to str. If only one element, just write "element1" to str. | |
579 | */ | |
c7e5fe79 SB |
580 | void strbuf_add_separated_string_list(struct strbuf *str, |
581 | const char *sep, | |
582 | struct string_list *slist); | |
f6f77559 | 583 | |
6afbbdda | 584 | /** |
06379a65 MH |
585 | * Free a NULL-terminated list of strbufs (for example, the return |
586 | * values of the strbuf_split*() functions). | |
587 | */ | |
c7e5fe79 | 588 | void strbuf_list_free(struct strbuf **list); |
f1696ee3 | 589 | |
9ea57964 DS |
590 | /* |
591 | * Remove the filename from the provided path string. If the path | |
592 | * contains a trailing separator, then the path is considered a directory | |
593 | * and nothing is modified. | |
594 | * | |
595 | * Examples: | |
596 | * - "/path/to/file" -> "/path/to/" | |
597 | * - "/path/to/dir/" -> "/path/to/dir/" | |
598 | */ | |
599 | void strbuf_strip_file_from_path(struct strbuf *sb); | |
600 | ||
c7e5fe79 SB |
601 | void strbuf_add_lines(struct strbuf *sb, |
602 | const char *prefix, | |
603 | const char *buf, | |
604 | size_t size); | |
895680f0 | 605 | |
6afbbdda | 606 | /** |
5963c036 MH |
607 | * Append s to sb, with the characters '<', '>', '&' and '"' converted |
608 | * into XML entities. | |
609 | */ | |
c7e5fe79 SB |
610 | void strbuf_addstr_xml_quoted(struct strbuf *sb, |
611 | const char *s); | |
5963c036 | 612 | |
399ad553 JK |
613 | /** |
614 | * "Complete" the contents of `sb` by ensuring that either it ends with the | |
615 | * character `term`, or it is empty. This can be used, for example, | |
616 | * to ensure that text ends with a newline, but without creating an empty | |
617 | * blank line if there is no content in the first place. | |
618 | */ | |
619 | static inline void strbuf_complete(struct strbuf *sb, char term) | |
620 | { | |
621 | if (sb->len && sb->buf[sb->len - 1] != term) | |
622 | strbuf_addch(sb, term); | |
623 | } | |
624 | ||
895680f0 JH |
625 | static inline void strbuf_complete_line(struct strbuf *sb) |
626 | { | |
399ad553 | 627 | strbuf_complete(sb, '\n'); |
895680f0 JH |
628 | } |
629 | ||
0705fe20 JK |
630 | /* |
631 | * Copy "name" to "sb", expanding any special @-marks as handled by | |
c7c33f50 | 632 | * repo_interpret_branch_name(). The result is a non-qualified branch name |
0705fe20 JK |
633 | * (so "foo" or "origin/master" instead of "refs/heads/foo" or |
634 | * "refs/remotes/origin/master"). | |
635 | * | |
636 | * Note that the resulting name may not be a syntactically valid refname. | |
0e9f62da JK |
637 | * |
638 | * If "allowed" is non-zero, restrict the set of allowed expansions. See | |
c7c33f50 | 639 | * repo_interpret_branch_name() for details. |
0705fe20 | 640 | */ |
c7e5fe79 SB |
641 | void strbuf_branchname(struct strbuf *sb, const char *name, |
642 | unsigned allowed); | |
0705fe20 JK |
643 | |
644 | /* | |
645 | * Like strbuf_branchname() above, but confirm that the result is | |
646 | * syntactically valid to be used as a local branch name in refs/heads/. | |
647 | * | |
648 | * The return value is "0" if the result is valid, and "-1" otherwise. | |
649 | */ | |
c7e5fe79 | 650 | int strbuf_check_branch_ref(struct strbuf *sb, const char *name); |
a552de75 | 651 | |
c2694952 MD |
652 | typedef int (*char_predicate)(char ch); |
653 | ||
c7e5fe79 | 654 | void strbuf_addstr_urlencode(struct strbuf *sb, const char *name, |
c2694952 | 655 | char_predicate allow_unencoded_fn); |
679eebe2 | 656 | |
9a0a30aa | 657 | __attribute__((format (printf,1,2))) |
c7e5fe79 | 658 | int printf_ln(const char *fmt, ...); |
9a0a30aa | 659 | __attribute__((format (printf,2,3))) |
c7e5fe79 | 660 | int fprintf_ln(FILE *fp, const char *fmt, ...); |
9a0a30aa | 661 | |
88d5a6f6 | 662 | char *xstrdup_tolower(const char *); |
13ecb463 | 663 | char *xstrdup_toupper(const char *); |
88d5a6f6 | 664 | |
6afbbdda | 665 | /** |
30a0ddb7 JK |
666 | * Create a newly allocated string using printf format. You can do this easily |
667 | * with a strbuf, but this provides a shortcut to save a few lines. | |
668 | */ | |
669 | __attribute__((format (printf, 1, 0))) | |
670 | char *xstrvfmt(const char *fmt, va_list ap); | |
671 | __attribute__((format (printf, 1, 2))) | |
672 | char *xstrfmt(const char *fmt, ...); | |
673 | ||
fda5d959 CW |
674 | int starts_with(const char *str, const char *prefix); |
675 | int istarts_with(const char *str, const char *prefix); | |
676 | ||
677 | /* | |
678 | * If the string "str" is the same as the string in "prefix", then the "arg" | |
679 | * parameter is set to the "def" parameter and 1 is returned. | |
680 | * If the string "str" begins with the string found in "prefix" and then a | |
681 | * "=" sign, then the "arg" parameter is set to "str + strlen(prefix) + 1" | |
682 | * (i.e., to the point in the string right after the prefix and the "=" sign), | |
683 | * and 1 is returned. | |
684 | * | |
685 | * Otherwise, return 0 and leave "arg" untouched. | |
686 | * | |
687 | * When we accept both a "--key" and a "--key=<val>" option, this function | |
688 | * can be used instead of !strcmp(arg, "--key") and then | |
689 | * skip_prefix(arg, "--key=", &arg) to parse such an option. | |
690 | */ | |
691 | int skip_to_optional_arg_default(const char *str, const char *prefix, | |
692 | const char **arg, const char *def); | |
693 | ||
694 | static inline int skip_to_optional_arg(const char *str, const char *prefix, | |
695 | const char **arg) | |
696 | { | |
697 | return skip_to_optional_arg_default(str, prefix, arg, ""); | |
698 | } | |
699 | ||
700 | static inline int ends_with(const char *str, const char *suffix) | |
701 | { | |
702 | size_t len; | |
703 | return strip_suffix(str, suffix, &len); | |
704 | } | |
705 | ||
d1df5743 | 706 | #endif /* STRBUF_H */ |